McpServer

McpServer is a context server used for todo management, session logs, context search, repository operations, and GitHub issue synchronization. It exposes an HTTP API with Swagger UI and also supports an MCP over STDIO transport. The server supports multi-tenant workspaces based on the X-Workspace-Path header and can back each workspace with either a YAML file or a SQLite database for todo storage. You can interact with the API to manage todos, view and search contexts, operate on repositories, and synchronize GitHub issues. When running in STDIO mode, you can drive the server through standard IO, which is useful for embedding in other tooling or CI pipelines. To start, run the server in HTTP mode and then navigate to the Swagger UI to discover endpoints and examples.

• Prerequisites:

  • .NET SDK as defined by global.json in the repository
  • PowerShell 7+ (for script-based start and management tasks)
  • Windows SDK tools if you plan to package MSIX (optional)
  • Optional: GitHub CLI (gh) for GitHub issue endpoints

• Install steps:

  1. Clone the repository: git clone <repository-url>
  2. Restore and build the solution (as shown in Quick Start):

     dotnet restore McpServer.sln
     dotnet build McpServer.sln -c Staging
     

  3. Run the server (default HTTP mode):

     .\scripts\Start-McpServer.ps1 -Configuration Staging -Instance default
     

  4. Open the Swagger UI to explore endpoints: http://localhost:7147/swagger

• Optional alternative run (STDIO MCP mode):

  • Start the server in STDIO mode to interact via standard IO:

    dotnet run --project src/McpServer.Support.Mcp/McpServer.Support.Mcp.csproj -c Staging -- --transport stdio --instance default
    

• Notes:

  • The primary configuration lives under Mcp in the appsettings, with per-instance overrides under Mcp:Instances.
  • For multi-instance setups, you can start multiple instances and use the provided scripts to test cross-instance scenarios.

• The server supports multi-tenant workspaces via the X-Workspace-Path header. Ensure clients set this header to route requests to the correct workspace.
• Todo storage can be YAML file-backed or SQLite-backed depending on your Mcp:TodoStorage:Provider setting; you can migrate data between backends using the provided scripts.
• GraphRAG features are optional and disabled by default. If you enable it, provide a runtime backend and ensure secrets are supplied via environment variables or host configuration rather than in repo config.
• Environment variables take precedence over config file values. Common overrides include PORT and MCP_INSTANCE to influence runtime port and default instance selection.
• The API surface covers Todo, Context, SessionLog, Repo, GitHub, Sync, and Workspace endpoints, with Swagger available for exploration. For CI environments, consider using the STDIO transport integration for embedding the MCP server into pipelines.