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.
bendtherules