Feat/export csv extent types#601
Closed
MVytautas wants to merge 35 commits intographprotocol:mainfrom
Closed
Conversation
Four parallel research agents produced STACK.md, FEATURES.md, ARCHITECTURE.md, and PITFALLS.md covering the MCP server that bridges the Geo Protocol GraphQL API for non-technical editors. SUMMARY.md synthesizes findings into roadmap implications. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…dation - Create packages/mcp-server with MCP SDK, Effect, graphql-request, Zod deps - Add Zod-validated config loader for spaces.json with 3 pre-configured spaces - Define Effect tagged errors (ConfigError, PrefetchError, GraphQLError) - Add tsconfig, vitest config, and root tsconfig reference Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…try point - Create graphql-client.ts with types/entities queries and fetch functions - Create prefetch.ts with parallel space prefetch and 2-minute timeout - Create index.ts entry point: config -> prefetch -> McpServer -> stdio - All logging via Effect (stderr), zero console.log calls - Auto-fix formatting with biome lint:fix Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- In-memory store wraps prefetched data with space/type lookup - Fuzzy space name resolver with cascading match strategies - Markdown formatters for spaces list and entity types table - list_spaces tool registered with MCP annotations (readOnlyHint) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- get_entity_types with Zod input validation and GRC-20 vocabulary - Fuzzy space name resolution for flexible user input - Both tools registered in index.ts startup pipeline - Auto-formatted all new files with Biome (tabs to spaces) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…pace The endpoint was `api.testnet.geobrowser.io` but the correct URL from geo-sdk is `testnet-api.geobrowser.io`. Removed placeholder spaces with TBD UUIDs, keeping only the AI space that has a real ID. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… entity data - Replace TYPES_LIST_QUERY with TYPES_WITH_PROPERTIES_QUERY to fetch property schemas per type - Add relationsList to ENTITIES_QUERY for entity relationship data - Retain full entity values and relations in prefetch pipeline (stop stripping data) - Add pagination loop with 10000 page size for large spaces - Expand store with entity storage, property registry, entity/type name indexes - Add entity lookup, search, and name resolution methods to PrefetchedStore - Backward-compatible: existing tools compile unchanged Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…operty names - Create formatters/entities.ts with formatEntity, formatEntityList, extractPropertyValue - Entity formatter resolves property names, type names, and relation targets via store - Show all type schema properties including empty ones as "(empty)" - Truncate text values exceeding 500 chars with total length indicator - Display orphaned properties not in type schema - Relations section with resolved names for relation types and targets - Include prefetch timestamp footer on all formatted output - Enhance types formatter with Properties column showing property names per type - Fix Biome formatting issues across modified files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- search_entities: case-insensitive name search with optional type filter, pagination - get_entity: full entity detail by ID with all properties and relations - list_entities: browse entities by human-readable type name with pagination - Add resolveType helper to fuzzy.ts for type name resolution - All tools follow established registerXxxTool pattern with Zod schemas Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Import and register search_entities, get_entity, list_entities - Update log message to reflect 5 registered tools - get_entity_types already compatible with TypeInfoWithProperties (no changes needed) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…names Split the combined types+properties GraphQL query into separate queries so properties come from the root `properties` endpoint. Type-to-property mappings are now inferred from entity value data, which is more accurate when the API returns types with duplicate names but different IDs. The fuzzy resolver returns all matching types (not just the first) so tools correctly aggregate entities across duplicate type IDs. The types formatter deduplicates by name and merges properties. Also updates integration docs to reflect the chosen MCP Server + Claude Code approach and adds .claude/.planning to .gitignore. Co-Authored-By: Claude <noreply@anthropic.com>
Fetches types, properties, entities, and relations via GraphQL and writes them to structured CSV files organized by space ID. Supports pagination and handles duplicate property name disambiguation. Co-Authored-By: Claude <noreply@anthropic.com>
…yment Add a stateless Streamable HTTP entry point using Express so the MCP server can run as a long-lived container on Railway. Extract shared tool registration into a helper used by both stdio and HTTP entry points. - Add `src/http.ts` with Express + StreamableHTTPServerTransport - Add `src/register-tools.ts` shared helper - Add `Dockerfile.mcp` multi-stage build (node:22-alpine) - Add express dependency and start/dev:http scripts - Update `.dockerignore` allowlist for mcp-server Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Railway's BuildKit rejects cache mount IDs that aren't prefixed with its internal cache key. Remove --mount=type=cache directives from pnpm fetch and install steps. Co-Authored-By: Claude <noreply@anthropic.com>
Railway needs the full monorepo as build context. Keep the Dockerfile at the repo root and use RAILWAY_DOCKERFILE_PATH to point to it. Co-Authored-By: Claude <noreply@anthropic.com>
New tool that traverses the knowledge graph from a known entity, returning connected entities via outgoing, incoming, or both directions. Supports filtering by relation type name with fuzzy matching and pagination via limit/offset. Adds reverse relations index to the store for efficient incoming edge lookups, along with resolveRelationTypeIds for name-based relation type resolution. Also adds Root space to the spaces config. Co-Authored-By: Claude <noreply@anthropic.com>
Rewrite tool descriptions to clarify fuzzy matching behavior, pagination defaults, and recommended workflow between tools. Add server-level description and instructions to both stdio and HTTP transports to guide LLM clients through the discovery flow. Co-Authored-By: Claude <noreply@anthropic.com>
On Railway the process stays alive indefinitely, so the prefetched cache goes stale. Add a setInterval-based refresh loop that re-fetches all space data and atomically swaps the store. On failure, the old store continues serving requests with no disruption. Configurable via REFRESH_INTERVAL_MINUTES env var (default: 10, set to 0 to disable). The /health endpoint now reports cacheTimestamp and refreshIntervalMinutes for monitoring. Co-Authored-By: Claude <noreply@anthropic.com>
These directories contain local development tooling artifacts and should not be part of the repository. Updated .gitignore accordingly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
HTTP Transport & Deployment (src/http.ts, Dockerfile.mcp, .dockerignore)
New Express-based HTTP entrypoint using Streamable HTTP transport (stateless mode)
Multi-stage Dockerfile optimized for Railway deployment (node:22-alpine)
Health endpoint at /health exposing cache timestamp and refresh interval
Configurable via PORT and REFRESH_INTERVAL_MINUTES env vars
Graph Traversal (src/tools/get-related-entities.ts, src/store.ts)
New get_related_entities tool supporting outgoing, incoming, and bidirectional traversal
Reverse relations index built at prefetch time for O(1) incoming lookups
Fuzzy relation type name resolution (exact > prefix > substring)
Pagination support via limit/offset
Background Cache Refresh (src/http.ts, src/store.ts)
Periodic re-prefetch on a configurable interval (default 10 min)
Hot-swaps the in-memory store without downtime
Failures keep stale data and log a warning
Tool Registration Refactor (src/register-tools.ts)
Extracted tool registration into a shared registerTools function used by both stdio and HTTP entrypoints
Improved tool descriptions and added instructions to the MCP server metadata
…improvements Enable search_entities and get_entity_types to work across all spaces when the space parameter is omitted. Add property-based filtering (eq, contains, gt/gte/lt/lte, exists/not_exists) and sorting to search_entities and list_entities. Set a default limit of 50 on all list/search tools to prevent unbounded responses. Add auto-fallback in search_entities: when a space-specific search returns no results, automatically retry across all spaces and surface the results with an explanatory note. Improve get_related_entities error messages to show available relation type names when a filter produces no matches. Update tool descriptions and server instructions to guide agents toward cross-space searches first, with clear examples for incoming/outgoing relation traversal. Co-Authored-By: Claude <noreply@anthropic.com>
Return warnings when filter or sort property names cannot be resolved, surfacing feedback to the caller instead of silently skipping. Also normalize underscores to spaces in property name matching for friendlier fuzzy lookups. Co-Authored-By: Claude <noreply@anthropic.com>
…ools Allow filtering entities by their graph relations to other named entities. Supports fuzzy entity name matching, optional relation type filtering, and directional traversal (outgoing/incoming). Co-Authored-By: Claude <noreply@anthropic.com>
Show a Relations column in entity type listings that displays the relation types each entity type uses along with their target types (e.g., "location → City"). This helps users discover the right relation_type and direction parameters before using related_to in search_entities or list_entities. Also updates tool descriptions for search and list to guide users toward calling get_entity_types first for relation-based queries. Co-Authored-By: Claude <noreply@anthropic.com>
Add a compact=true parameter to search_entities, list_entities, and get_related_entities that returns results as a token-efficient markdown table (Name, Type, ID) instead of full entity cards. This allows LLMs to scan large result sets cheaply before fetching details with get_entity. Co-Authored-By: Claude <noreply@anthropic.com>
list_entities now accepts an optional space parameter. When omitted, it queries all spaces at once using the same cross-space pattern as search_entities — preventing Claude from missing entities of the same type that live in multiple spaces (e.g., Bounty in AI/Crypto/Health). System prompt in both transports updated with an explicit IMPORTANT notice that the same type often exists in multiple spaces, and a recommended 4-step workflow that leads with cross-space calls and shows how to use filters for property-based queries rather than fetching everything and filtering manually. get_entity_types description strengthened to emphasise querying without a space to discover all spaces that contain a given type. search_entities description adds a note on using filters for property-based searches. Co-Authored-By: Claude <noreply@anthropic.com>
LLMs were incorrectly guessing a space based on entity type (e.g., searching only "Crypto" for Bounties), missing results in other spaces. Add an explicit rule and anti-pattern/correct-pattern example to system instructions, and strengthen the `space` parameter descriptions across search_entities, list_entities, and list_spaces to make clear that space should never be inferred — only passed when the user explicitly requests it. Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.