convez.ai
MCP ServerIntegração & APIsAvançado
sbuyevich

Dev Context MCP Server

sbuyevich/dev-context-mcp-server

Indexação segura de pacotes NuGet privados para agentes de código

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP em .NET 10 que indexa pacotes NuGet internos e documentação corporativa, permitindo que agentes de código acessem APIs privadas, metadados de versão e símbolos públicos sem executar assemblies. Usa SQLite/FTS5 para busca rápida e oferece descoberta de bibliotecas, seleção de versão semântica e citações estáveis para documentação.

Instalação

$npx convez-ai sbuyevich/dev-context-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Fornecer contexto de pacotes internos a agentes de IA durante desenvolvimento
  • Buscar documentação e APIs em repositórios corporativos de NuGet isolados por versão
  • Inspecionar assinaturas públicas de tipos e membros sem carregar assemblies

Veredito

Solução robusta e bem arquitetada para empresas que precisam aterrar agentes de código em ecossistemas .NET privados. Implementação séria com testes, CLI configurável e separação clara entre indexação e retrieval — recomendado para equipes que mantêm múltiplas versões de pacotes internos.

README

A tradução para o português deste README ainda está na fila.

Dev Context MCP Server

Dev Context MCP is a .NET 10 Model Context Protocol server that gives coding agents grounded, version-aware access to internal NuGet packages and company documentation.

It indexes package metadata, README files, XML documentation, packaged text files, public .NET symbols, dependencies, target frameworks, and an optional documentation directory. Agents can then discover libraries, select an indexed version, search documentation, inspect real API signatures, and open the exact source material behind each answer.

The system never loads or executes package assemblies. Retrieval is served entirely from a local SQLite/FTS5 index.

Why This Project Exists

Coding agents often know public libraries but lack reliable context for private packages, generated API clients, environment-specific builds, and company standards. Dev Context MCP turns those sources into a small, deterministic MCP surface:

  • Package discovery by exact ID or implementation concept.
  • Explicit environment and semantic-version selection.
  • Documentation search isolated to one package version.
  • Metadata-only lookup of public types and members.
  • Stable citations that can be opened as MCP resources.
  • Machine-readable ok, not_found, and insufficient_evidence outcomes.

Generated clients do not need special handling. If a client is published as a NuGet package with public assemblies and useful documentation, it follows the same indexing and retrieval path as any other package.

How It Works

Index production and MCP retrieval are separate processes:

flowchart LR
    Feeds[NuGet feeds or local package folders]
    Docs[Company documentation folder]
    Indexer[DevContextMcp.Indexer]
    Database[(SQLite and FTS5)]
    Server[DevContextMcp.Server]
    Client[MCP client or coding agent]

    Feeds --> Indexer
    Docs --> Indexer
    Indexer -->|only writer| Database
    Database -->|read only| Server
    Client -->|stdio or Streamable HTTP| Server
  1. The one-shot Indexer reads configured sources and package-policy files.
  2. It safely downloads or opens selected .nupkg files.
  3. It extracts metadata, documents, and symbols without executing package code.
  4. It atomically publishes changed content to SQLite and updates FTS5.
  5. The Server opens the same database read-only and exposes MCP tools and resources.

Run only one Indexer process against a database at a time. The Server can stay independent of feeds and credentials because it never refreshes data itself.

Solution was desinged and implemented with Codex AI agent using specs and plans defined in design folder.

Indexer Configuration

Demo

Demo folder has

Quick Start

Prerequisites

  • The .NET SDK selected by global.json, currently .NET SDK 10.0.301 with latest-patch roll-forward.
  • Internet access when restoring packages and when indexing the bundled public NuGet example.
  • Node.js only if you want to use MCP Inspector.

1. Build and test

Run from the repository root:

dotnet restore .\DevContextMcp.slnx
dotnet build .\DevContextMcp.slnx --no-restore
dotnet test .\DevContextMcp.slnx --no-build --no-restore

2. Build the local index

The checked-in Indexer configuration uses:

  • NuGet.org for Formula.SimpleRepo.
  • Local prod and qa feeds under demo/data/nuget-repos.
  • Package policies under demo/data/indexer/nugets.
  • Company documents under demo/data/indexer/company-docs.

Run one complete indexing pass:

dotnet run --project .\src\DevContextMcp.Indexer\DevContextMcp.Indexer.csproj

The demo database is created at database/docs.db. Exit code 0 means all configured sources succeeded or no sources were configured. Exit code 1 means configuration failed, indexing was canceled, or at least one source did not complete successfully.

Re-running the command is safe. Content hashes prevent unchanged package data from being rewritten, while index-run history records each execution.

3. Start the MCP server

The checked-in development configuration starts stateless Streamable HTTP at:

http://127.0.0.1:2222/mcp
dotnet run --project .\src\DevContextMcp.Server\DevContextMcp.Server.csproj

HTTP is deliberately restricted to an unauthenticated loopback http:// address. It is suitable for local development, not shared-network deployment.

To use stdio instead:

dotnet run --project .\src\DevContextMcp.Server\DevContextMcp.Server.csproj `
  -- --DevContextMcp:Transport=stdio

Standard output is reserved for MCP protocol messages in stdio mode. Logs are written to standard error and to the configured Serilog file sink.

4. Connect MCP Inspector

For the default HTTP configuration, start the Server and then run:

npx -y @modelcontextprotocol/inspector

Choose Streamable HTTP and connect to http://127.0.0.1:2222/mcp.

For stdio, Inspector can launch the process directly:

npx -y @modelcontextprotocol/inspector dotnet run `
  --project .\src\DevContextMcp.Server\DevContextMcp.Server.csproj `
  -- --DevContextMcp:Transport=stdio

Try this workflow after connecting:

  1. Call resolve_library with Demo.Cities.
  2. Pass a returned ID such as nuget:prod/Demo.Cities to list_versions.
  3. Call query_docs or get_symbol with the selected version.
  4. Open a returned nuget:// citation under Resources.
  5. Query docs:company-docs for the bundled company-document examples.

MCP Surface

Tools

ToolPurposeImportant inputs
resolve_libraryFinds indexed NuGet packages or company documentation by ID, name, or concept.query, environment, includePrerelease, limit
list_versionsLists indexed package versions and identifies the recommended version.libraryId, includePrerelease
query_docsSearches version-scoped package evidence or company documents.libraryId, question, version, projectVersion, targetFramework, maxResults
get_symbolFinds a public type or member and returns its indexed signature and XML documentation.libraryId, symbol, version, projectVersion, targetFramework

get_symbol accepts fully qualified, simple, or partial names. If a lookup is ambiguous, it returns bounded candidates instead of silently choosing one. Symbol lookup is not supported for docs:company-docs.

Library IDs

Discovery returns stable IDs:

nuget:prod/Demo.Cities
nuget:qa/Demo.Cities
docs:company-docs

An environment-qualified NuGet ID never falls back to another environment. Legacy IDs such as nuget:Demo.Cities use the configured environment and source order.

Company documentation is one versionless library. query_docs and resource reads apply to it; NuGet version and symbol operations do not.

Resources and citations

Tool evidence points to read-only MCP resources:

nuget://{source}/{packageId}/{version}/artifact/{path}
nuget://{source}/{packageId}/{version}/symbol/{qualifiedName}
docs://company-docs/{path}

Opening a resource reads the exact indexed artifact or symbol. The Server does not contact a NuGet feed during retrieval.

Version Selection

For query_docs and get_symbol, one version is selected in this order:

  1. Exact version from the tool request.
  2. Exact projectVersion supplied as calling-project context.
  3. Environment-qualified version selection entry.
  4. Package-wide version selection entry.
  5. Latest indexed, listed stable version.
  6. Latest indexed, listed prerelease when prereleases are allowed.

The selected version must already be in the local index. Evidence from different package versions is never combined.

Indexer Configuration

The Indexer loads src/DevContextMcp.Indexer/appsettings.json from the executable directory, followed by standard .NET environment-variable and command-line overrides.

A minimal configuration looks like this:

{
  "DevContextMcp": {
    "DatabasePath": "data/docs.db",
    "IndexerSource": {
      "NugetsPath": "nugets",
      "Documents": {
        "RootPath": "C:\\company\\docs",
        "Extensions": [ ".md", ".txt" ]
      }
    },
    "NugetPackages": [
      {
        "Name": "companyProduction",
        "Environment": "production",
        "ServiceIndex": "https://packages.example/v3/index.json",
        "MaxPackages": 100
      }
    ],
    "Indexing": {
      "MaxPackageBytes": 104857600,
      "MaxDocumentBytes": 20971520,
      "MaxArchiveEntries": 10000,
      "MaxExtractedBytes": 524288000,
      "MaxCompressionRatio": 200,
      "MaxDocumentChars": 4000,
      "PackageDownloadTimeout": "00:02:00"
    }
  }
}

Each NuGet package source is either an absolute HTTP/HTTPS NuGet v3 service index or a local directory containing .nupkg files. Name is the unique source identity used by citations and MCP SourceId. Environment is stored separately and used in library IDs such as nuget:production/Company.Foundation.

Package policy files

Create one JSON file per exact package ID anywhere below IndexerSource:NugetsPath:

{
  "Environment": "production",
  "PackageId": "Company.Foundation",
  "MaxVersionsPerPackage": 3,
  "IncludePrerelease": false,
  "IncludeUnlisted": false
}

Files are loaded recursively and matched to each NuGet source by Environment. The version limit controls what is selected on that run; lowering it does not remove versions already stored in the index.

Deletion is explicit. Keep a tombstone file to remove every indexed version of a package from one environment:

{
  "Delete": true,
  "Environment": "production",
  "PackageId": "Company.Foundation"
}

Removing a policy file, removing a package from a feed, or reducing a version limit does not delete previously indexed data. A matching Delete: true tombstone is the deletion mechanism.

Company documentation

The optional IndexerSource:Documents section indexes one directory recursively as docs:company-docs.

  • Only configured extensions are included.
  • Hidden entries, dot-prefixed entries, links, and reparse points are skipped.
  • Files must be valid UTF-8 and stay within the configured size limit.
  • Each file is stored as a complete resource and split into searchable chunks.

Server Configuration

The Server separately loads src/DevContextMcp.Server/appsettings.json from its executable directory. Point it at the same database written by the Indexer:

{
  "DevContextMcp": {
    "Transport": "stdio",
    "Http": {
      "Url": "http://127.0.0.1:2222",
      "Path": "/mcp"
    },
    "DatabasePath": "data/docs.db",
    "Retrieval": {
      "EnvironmentOrder": [ "production", "qa" ],
      "SourceOrder": [ "internal" ],
      "DefaultMaxResults": 8,
      "MaxResults": 25,
      "MaxResponseBytes": 102400,
      "QueryTimeout": "00:00:05",
      "MinimumEvidenceScore": 0.15,
      "AmbiguousSymbolLimit": 10
    },
    "ToolLogging": {
      "MaxPayloadBytes": 32768
    }
  }
}

Key behavior:

  • DatabasePath is opened read-only and must already contain a current index.
  • EnvironmentOrder controls legacy unqualified NuGet IDs.
  • Result count, evidence score, response bytes, and query duration are bounded.
  • HTTP validation permits only an absolute loopback HTTP URL.
  • Invalid configuration fails startup instead of silently falling back.

Environment variables use double underscores:

$env:DevContextMcp__DatabasePath = "C:\dev-context\data\docs.db"
$env:DevContextMcp__Retrieval__EnvironmentOrder__0 = "production"

Command-line overrides use colon-separated keys:

dotnet run --project .\src\DevContextMcp.Server\DevContextMcp.Server.csproj `
  -- --DevContextMcp:Transport=http `
     --DevContextMcp:Http:Url=http://127.0.0.1:5034

Restart the Server after changing its configuration. Rerun the Indexer after changing indexing configuration, package policies, feeds, or source documents.

Indexed Content and Safety

For each selected NuGet version, the Indexer stores:

  • Package identity, title, description, authors, tags, URLs, and publication state.
  • Dependencies and target frameworks.
  • Markdown, text, and XML documentation.
  • Public symbols from assemblies under ref/ and lib/.
  • Content hashes, searchable document chunks, and run diagnostics.

Package archives are treated as untrusted input. Processing enforces package size, document size, archive entry count, extracted-size, and compression-ratio limits. Paths are validated against traversal, and assemblies are inspected through metadata APIs rather than loaded into the runtime.

SQLite publication is transactional. A failed package refresh preserves the last successfully indexed data. The Server applies query timeouts, result limits, response budgets, and citation-safe URI encoding.

Do not put feed credentials or API tokens in package-policy files or the checked-in settings. Source authentication is intentionally isolated behind an infrastructure interface for future approved credential providers.

Distribution

Create self-contained Windows x64 builds:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\dist.ps1

Outputs are written under artifacts/dist/win-x64:

server/
indexer/
data/
server.cmd
indexer.cmd
DevContextMcp.Server-win-x64.zip
DevContextMcp.Indexer-win-x64.zip

The script publishes both applications, rewrites their database and package paths for the distribution layout, creates launchers, and validates each ZIP. If no usable .NET SDK is installed, it can download the SDK version from global.json into artifacts/tools/dotnet without changing the machine-wide installation.

For a combined deployment, keep the extracted server, indexer, and data directories under the same parent. Run indexer.cmd to refresh the index and server.cmd to serve it.

Development and Testing

Run the complete suite:

dotnet test .\DevContextMcp.slnx

The test projects cover:

  • Configuration validation and path resolution.
  • Project dependency and registration boundaries.
  • Archive safety, chunking, hashing, and metadata symbol extraction.
  • Version resolution, ranking, response budgets, and serialization.
  • SQLite indexing, FTS retrieval, idempotency, and deletion tombstones.
  • Company-document indexing and retrieval.
  • MCP tool discovery, resources, stdio, HTTP, startup, and failure behavior.
  • Indexer child-process exit codes and diagnostics.

When changing retrieval behavior, preserve deterministic ordering, package version isolation, explicit failure statuses, and resolvable citations. When changing indexing behavior, preserve archive safety and atomic publication.

Further Reading

The design documents contain historical stage context. This README describes the current repository and its end-to-end operating model.

Ver o original no GitHub

Bom para

Relacionados