Each MCP tool handler now sets:
- LANGFUSE_TRACE_OUTPUT_ATTR on tool spans (maps to top-level trace output)
- LANGFUSE_OBSERVATION_INPUT_ATTR and LANGFUSE_OBSERVATION_OUTPUT_ATTR
for detailed child observation views
HTTP root span renamed to 'mcp_http_request' for consistency with stdio.
All attribute keys use constants from langfuse-transport.ts.
Wrap each MCP tool handler in withSpan()/withSpanContext() to create
individual named spans per tool call:
- ask262_search_spec_sections
- ask262_get_section_content
- ask262_evaluate_in_engine262
Each span includes:
- langfuse.observation.input: JSON of tool arguments (query, sectionIds, code)
- tool name and relevant metadata as span attributes
This makes the Langfuse trace hierarchy show which MCP tool was called
and what input it received, nested under the root HTTP/stdio request span.
Add Langfuse as an OTel trace transport for MCP request lifecycle tracking.
Changes:
- New src/lib/langfuse-transport.ts: initializes LangfuseSpanProcessor when
ASK262_LANGFUSE_ENABLED=true with valid credentials
- src/lib/tracing.ts: add metadata to TraceContext, propagate it to child spans,
use startActiveSpan for proper OTel context, add setupTracing() entry point,
add getSessionMetadata() for version/transport metadata
- src/lib/logger.ts: include TraceContext.metadata in JSON log mixin
- src/mcp-server-{http,stdio}.ts: call setupTracing() at startup, pass
version/transport metadata through withSpan/withSpanContext
- src/lib/fireworks-embeddings.ts: wrap API calls in withSpan() with gen_ai
attributes for Langfuse generation/cost tracking
- .env.example: add LANGFUSE_* configuration variables
- AGENTS.md: document Langfuse integration
- package.json: add @langfuse/tracing, @langfuse/otel, @opentelemetry/sdk-node
Simplify logger by removing getConsoleLogLevel() and LOG_LEVEL_VALUES.
When ASK262_LOG_CONSOLE=true, console output uses the same level as
file logging (ASK262_LOG_LEVEL).
Console output is now disabled by default. Set ASK262_LOG_CONSOLE=true
to enable pretty-printed logs routed to stderr. This prevents:
- Stdio MCP protocol corruption from stdout noise
- Noisy test output during bun test runs
Also fixes misleading comments about HTTP/stdio log level defaults.
Replace naive manual .stringValue()/.value fallback with engine262's
inspect() function so console.log outputs readable strings instead of
raw engine262 internal objects.
Closes#5
Previously when recursive=true, child sections were fetched into sectionsData
but never included in the returned sections array. Now child sections are
properly appended to the output when recursive fetching is enabled.
- Refactor section building from .map() to for..of for clarity
- Add logic to append child sections not in original request
- Add test coverage for recursive child section inclusion
The getSectionContent tool schema and implementation now use `childrenSectionIds` (array of strings) instead of the previous pagination fields `partIndex` and `totalParts`. Updated Zod schema, output types, data handling, and returned objects accordingly. This change simplifies section handling by focusing on child section relationships rather than pagination.
Added fallback to `process.env.COOLIFY_URL` before `MCP_PUBLIC_URL` when constructing the public URL for the MCP inspector, ensuring the correct base URL is used in environments where COOLIFY_URL is set.
- Define /mcp endpoint before mounting inspector at /
- Ensures specific routes are matched before catch-all
- Prevents inspector from intercepting MCP requests
- Eliminated `content` property from `searchSpecResultSchema` and output mapping.
- Updated `toolMetadata` description to reflect that only section references are returned and content must be fetched via `ask262_get_section_content`.
- Adjusted TypeScript code accordingly.
- Replaced the old “Prerequisites” section with an “Available Tools” table describing the three core commands.
- Added a “Quick Start (Hosted Instance)” section with configuration snippets for Claude Desktop and OpenCode.
- Created a detailed “Local Installation” / “Setup” section including cloning, installing, and global install commands.
- Updated environment configuration instructions and clarified .env usage.
- Consolidated MCP client configuration examples (stdio and http) with explicit server start commands.
- Provided updated spec‑building steps and clarified directory contents.
- Cleaned up duplicated installation instructions and improved overall layout for better readability.
- Insert console.error statements to trace loading, initialization, execution, and mark collection.
- Log creation of agent and realm, trace start/stop, and code execution progress.
- Output captured mark count.
- Simplify fatal error handling with a single error message variable and console.error output.
- Import path and fileURLToPath for path resolution.
- Rename imported STORAGE_DIR to STORAGE_DIR_REL.
- Compute STORAGE_DIR as an absolute path relative to the script’s directory.
---
## Explanation
The diff only modifies `Readme.md`, changing the OpenCode configuration snippet. The update replaces the old local config path with a global one, adds a `$schema` reference, restructures the `command` field, and introduces `type` and `enabled` properties. Therefore, a **docs**‑type conventional commit is appropriate, describing the documentation change.
Removed the outdated Setup documentation and introduced a new Development section that includes cloning instructions, spec setup steps, and guidance on building the knowledge graph for custom ECMAScript specifications. This reorganization clarifies the workflow for developers and users building the project from source.
Update README to specify pulling the `qwen3-embedding:0.6b` model and document the optional `OLLAMA_HOST` environment variable. Adjust server code to import `EMBEDDING_MODEL`, use it for Ollama embeddings, and pass `process.env.OLLAMA_HOST` as the base URL.
Deleted the `config.json` entry from the package file list and removed the corresponding `CONFIG_FILE` constant, cleaning up unused configuration references.
bendtherules