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

MCP Documentation Server

sbuyevich/mcp-doc-server

Indexa e consulta documentação de pacotes NuGet para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP em .NET 10 que indexa e disponibiliza documentação de pacotes NuGet internos para agentes de código. Oferece busca por versão, recuperação de README, inspeção de símbolos públicos e citações estáveis sem executar código.

Instalação

$npx convez-ai sbuyevich/mcp-doc-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
1

Casos de uso

  • Descoberta de APIs internas por agentes de código
  • Documentação versionada de pacotes gerados automaticamente
  • Inspeção de símbolos públicos sem execução de código

Veredito

Ferramenta especializada para equipes .NET que precisam integrar agentes IA com bases de documentação NuGet internas. Stage 3 funcional, mas ainda requer configuração manual e é voltada para desenvolvimento on-premises.

README

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

MCP Documentation Server

A .NET 10 Model Context Protocol server for helping coding agents discover and correctly use internal NuGet packages, including generated API-client packages.

Stage 3 adds version-aware NuGet retrieval over the SQLite/FTS5 index. The server can resolve packages, select versions, query README and XML documentation, inspect public symbols, and return stable citations without executing package code.

Prerequisites

  • .NET SDK 10.0.204 or a compatible 10.0 patch selected by global.json.

Build and test

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

Run the indexing worker

The Worker is the only process that writes the index. Run it continuously:

dotnet run --project .\src\McpDocServer.Indexing.Worker\McpDocServer.Indexing.Worker.csproj

It indexes immediately, then waits for Indexing:RefreshInterval after each completed run before starting the next one. To perform one refresh and exit:

dotnet run --project .\src\McpDocServer.Indexing.Worker\McpDocServer.Indexing.Worker.csproj -- --once

One-shot execution exits 0 after a successful run or when no sources are configured. It exits 1 after a failed or partially successful run.

Run over stdio

dotnet run --project .\src\McpDocServer.Host\McpDocServer.Host.csproj

Standard output is reserved for MCP protocol messages. Application and startup logs are written to standard error.

Example MCP client configuration:

{
  "mcpServers": {
    "internal-docs": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\path\\to\\mcp-doc-server\\src\\McpDocServer.Host\\McpDocServer.Host.csproj"
      ]
    }
  }
}

For a client launched outside the repository, use an absolute project path.

Run over Streamable HTTP

Start the same host in local HTTP mode:

dotnet run --project .\src\McpDocServer.Host\McpDocServer.Host.csproj `
  -- --McpDocServer:Transport=http

Connect a Streamable HTTP MCP client to:

http://127.0.0.1:5034/mcp

HTTP mode is stateless and intentionally unauthenticated for local development. Configuration validation restricts it to a loopback HTTP URL. Shared-network binding, TLS, authentication, authorization, and CORS remain Stage 5 work.

Test with MCP Inspector

For stdio, launch Inspector from the repository root:

npx -y @modelcontextprotocol/inspector dotnet run --project .\src\McpDocServer.Host\McpDocServer.Host.csproj

The host loads appsettings.json from its executable directory, independent of the caller's working directory. Configure an absolute DatabasePath when the index should live outside the repository.

To inspect HTTP mode, start the server separately with the HTTP command above, select Streamable HTTP in Inspector, and connect to http://127.0.0.1:2222/mcp.

After connecting:

  1. Open Tools and call resolve_library with an indexed package ID.
  2. Pass the returned nuget:{environment}/{packageId} value to list_versions.
  3. Call query_docs or get_symbol with a concrete version.
  4. Open Resources to read cited artifact and symbol URIs.

Tools

  • resolve_library: find indexed NuGet packages by ID or descriptive text, optionally within one environment.
  • query_docs: retrieve ranked, version-isolated documentation evidence.
  • get_symbol: inspect a public type or member, including XML documentation.
  • list_versions: list indexed semantic versions and the recommendation.

The tools return structured ok, not_found, or insufficient_evidence results.

Resources

Tool citations can be read through these MCP resource templates:

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

Resources are served only from the local index; retrieval never contacts the NuGet feed.

Configuration

The Host and Worker have separate appsettings.json files. Both use the McpDocServer root section and standard .NET environment-variable and command-line overrides.

Host configuration:

{
  "McpDocServer": {
    "Transport": "stdio",
    "Http": {
      "Url": "http://127.0.0.1:2222",
      "Path": "/mcp"
    },
    "DatabasePath": "data/docs.db",
    "RecommendedVersions": {
      "Company.Foundation": "4.0.0",
      "nuget:qa/Company.Foundation": "4.1.0-beta.1"
    },
    "Retrieval": {
      "EnvironmentOrder": [ "production", "qa" ],
      "SourceOrder": [ "internal" ],
      "DefaultMaxResults": 8,
      "MaxResults": 25,
      "MaxResponseBytes": 102400,
      "QueryTimeout": "00:00:05",
      "MinimumEvidenceScore": 0.15,
      "AmbiguousSymbolLimit": 10
    }
  }
}

Worker configuration:

{
  "McpDocServer": {
    "DatabasePath": "data/docs.db",
    "NuGetSources": [
      {
        "Name": "internal",
        "Environment": "production",
        "ServiceIndex": "https://packages.example/v3/index.json",
        "PackageIds": [ "Company.Foundation" ],
        "PackagePrefixes": [],
        "IncludePrerelease": false,
        "IncludeUnlisted": false,
        "MaxVersionsPerPackage": 3,
        "MaxPackages": 100
      }
    ],
    "RepositorySources": [],
    "Indexing": {
      "RefreshInterval": "01:00:00",
      "MaxPackageBytes": 104857600,
      "MaxDocumentBytes": 20971520,
      "MaxArchiveEntries": 10000,
      "MaxExtractedBytes": 524288000,
      "MaxCompressionRatio": 200,
      "MaxDocumentChars": 4000,
      "PackageDownloadTimeout": "00:02:00"
    }
  }
}

Configuration loading and overrides

The Host and Worker load their own appsettings.json from the executable directory. This makes JSON configuration independent of the directory from which the executable was launched.

Environment variables use double underscores between configuration segments:

$env:McpDocServer__DatabasePath = "C:\mcp-doc-server\data\docs.db"
$env:McpDocServer__Retrieval__EnvironmentOrder__0 = "production"

Command-line arguments use colon-separated paths:

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

Environment variables and command-line arguments override JSON values. Collection entries use a zero-based index. TimeSpan values use hh:mm:ss, so 01:00:00 means one hour and 00:02:00 means two minutes. Invalid values fail startup rather than silently falling back.

Configuration is read when the process starts. Restart the Host or Worker after changing its appsettings.json.

Host values

SettingMeaning and rules
TransportSelects one MCP transport for the process. Allowed lowercase values are stdio and http. The default is stdio.
Http:UrlBase address used in HTTP mode. It must be an absolute http:// loopback URL such as http://127.0.0.1:5034, with no path, query, fragment, or credentials. It is validated even when Transport is stdio.
Http:PathStreamable HTTP endpoint path mapped under Http:Url. It must start with / and cannot contain a query or fragment. The default is /mcp.
DatabasePathSQLite index opened read-only by the Host. It must point to the same database written by the Worker. Relative paths are resolved from the process working directory, so an absolute path is recommended.
RecommendedVersionsOptional package-to-version map. Use Company.Package for a package-wide recommendation or nuget:qa/Company.Package for an environment-specific recommendation. Keys are case-insensitive and values must be semantic versions such as 2.8.1 or 2.9.0-beta.1.
Retrieval:EnvironmentOrderCase-insensitive precedence for legacy IDs such as nuget:Company.Package. Each value must be a slug containing only letters, numbers, ., _, or -. Environments not listed here sort after listed environments by ordinal name.
Retrieval:SourceOrderCase-insensitive feed precedence within an environment. Source names not listed here sort after listed sources by ordinal name. Empty and duplicate values are rejected.
Retrieval:DefaultMaxResultsConfigured default result count. It must be positive and no greater than MaxResults. The current query_docs wire contract independently defaults MaxResults to 8, so keep these values aligned.
Retrieval:MaxResultsHard upper bound for requested result counts. It caps query_docs evidence and resolve_library matches. It must be positive and at least DefaultMaxResults.
Retrieval:MaxResponseBytesMaximum combined UTF-8 byte count of evidence text selected for a query_docs response. It does not include the surrounding JSON, metadata, or citations. Extra evidence is omitted with a truncation warning.
Retrieval:QueryTimeoutMaximum duration of each retrieval operation, including SQLite queries. A timeout returns a structured tool error instead of waiting indefinitely.
Retrieval:MinimumEvidenceScoreLowest accepted query_docs relevance score, from 0 through 1. Higher values return less, stronger evidence; lower values accept weaker matches.
Retrieval:AmbiguousSymbolLimitMaximum number of symbol candidates returned when get_symbol cannot select one unambiguous symbol. It must be positive.

Worker root values

SettingMeaning and rules
DatabasePathSQLite index created and updated by the Worker. Use exactly the same path as the Host. Relative paths are resolved from the process working directory.
NuGetSourcesNuGet feeds or local package folders to index. The collection may be empty; a one-shot run then succeeds without doing work.
RepositorySourcesReserved configuration for planned repository indexing. Entries are validated, but the current Worker indexes only NuGetSources; leave this as [].
IndexingScheduling, download, archive-safety, and document-processing limits described below.

NuGet source values

SettingMeaning and rules
NameStable, human-readable feed identity such as nuget.org or internal-qa. It appears in citations and SourceId. Names must be non-empty and unique, case-insensitively, across NuGet and repository sources.
EnvironmentSelection label such as production, qa, or public. It is required, compared case-insensitively, and may contain only letters, numbers, ., _, or -. Multiple feeds may share an environment.
ServiceIndexAbsolute HTTP/HTTPS NuGet v3 service-index URL, or a local package-folder path. Relative local paths are resolved from the Worker working directory; use an absolute path for predictable deployments.
PackageIdsExplicit package IDs to index. Use this for a known package, especially an unlisted package that search cannot discover. Empty strings are invalid.
PackagePrefixesNuGet search terms used to discover package IDs, followed by a case-insensitive StartsWith check. For example, Company. discovers matching listed packages. Search normally cannot discover new unlisted packages.
IncludePrereleaseWhen true, discovery and metadata selection may include prerelease versions. Retrieval still requires its request-level IncludePrerelease flag before selecting a prerelease by fallback or recommendation.
IncludeUnlistedWhen true, metadata selection may include unlisted versions. Prefer PackageIds because prefix search may not discover an unlisted package.
MaxVersionsPerPackageMaximum newest versions selected from each package during a refresh after prerelease and unlisted filters. It must be positive. There is no unlimited value; use a sufficiently large number when all available versions are required. Lowering it does not delete versions already indexed.
MaxPackagesMaximum distinct package IDs processed for this source after combining explicit IDs and prefix discoveries. It must be positive. IDs are ordered case-insensitively before the cap is applied.

At least one non-empty PackageIds or PackagePrefixes entry is required for each NuGet source.

Repository source values

SettingMeaning and rules
NameUnique source identity shared with the NuGet source namespace.
RootPathValid local repository root path. This is validated but not indexed by the current Worker.

Indexing values

SettingMeaning and rules
RefreshIntervalDelay after one continuous Worker run completes before the next run starts. Runs are sequential and never overlap within one Worker process. --once ignores this delay.
MaxPackageBytesMaximum downloaded .nupkg size in bytes. A package exceeding the limit fails before indexing.
MaxDocumentBytesMaximum uncompressed size of each README, text, or XML documentation entry read from a package.
MaxArchiveEntriesMaximum number of ZIP entries allowed in one .nupkg.
MaxExtractedBytesMaximum total declared uncompressed size across the archive. It also limits each selected managed assembly read.
MaxCompressionRatioMaximum allowed uncompressed-to-compressed ratio for an archive entry. This protects against highly compressed archive bombs.
MaxDocumentCharsMaximum character count of each searchable documentation chunk. Larger documents are split near a natural text boundary.
PackageDownloadTimeoutPer-package timeout covering package download, flush, and content hashing.

All indexing limits and intervals must be positive.

Environment and version selection

Discovery returns one qualified match per package and environment:

nuget:qa/Company.Foundation
nuget:production/Company.Foundation

A qualified ID searches only its named environment and never falls back to another one. A legacy ID such as nuget:Company.Foundation uses EnvironmentOrder, then SourceOrder when candidates are otherwise equally usable. Unlisted order values are still eligible; they sort after configured values.

Version selection uses this precedence:

  1. Exact Version supplied by the tool request.
  2. Exact ProjectVersion supplied as project context.
  3. Environment-qualified RecommendedVersions entry.
  4. Package-wide RecommendedVersions entry.
  5. Latest indexed, listed stable version.
  6. Latest indexed, listed prerelease when the request allows prereleases.

The Worker must first index a version before the Host can select it.

Paths, upgrades, and credentials

Give both processes the same preferably absolute DatabasePath. Although the JSON file is loaded from the executable directory, relative database and local source paths are resolved from the process working directory. If relative paths are used, launch both processes from the same directory.

After upgrading an existing database, run the Worker before the Host so it can apply the current schema migration.

On a successful run, the database contains package versions, artifacts, dependencies, target frameworks, public symbols, document chunks, FTS5 rows, and index-run history. Re-indexing an unchanged archive skips rewriting it. A failed package update preserves the prior successful version.

Do not place feed credentials or API tokens in these configuration objects. Future source integrations will obtain secrets from approved credential providers.

Generated API clients require no special configuration. Publish them as NuGet packages with a README, XML documentation, and public assemblies, then include their package IDs or prefixes in a configured NuGet source.

Design

Ver o original no GitHub

Bom para

Relacionados