{"id":27931379,"url":"https://github.com/ithena-one/mcp-governance-sdk","last_synced_at":"2025-05-07T03:15:11.110Z","repository":{"id":285620521,"uuid":"956274051","full_name":"ithena-one/mcp-governance-sdk","owner":"ithena-one","description":"Enterprise Governance Layer (Identity, RBAC, Credentials, Auditing, Logging, Tracing) for the Model Context Protocol SDK","archived":false,"fork":false,"pushed_at":"2025-04-04T03:45:08.000Z","size":638,"stargazers_count":24,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T03:15:06.145Z","etag":null,"topics":["ai","audit","compliance","credential-manager","credentials","enterprise","governance","identity","identity-management","llm","logging","mcp-server","modelcontextprotocol","open-telemetry","rbac","rbac-management","sdk","tracing","w3c"],"latest_commit_sha":null,"homepage":"https://ithena.one","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ithena-one.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-28T01:30:56.000Z","updated_at":"2025-05-06T20:46:59.000Z","dependencies_parsed_at":"2025-04-01T19:37:35.600Z","dependency_job_id":"355d8790-3bd8-4208-bd48-df2450eef068","html_url":"https://github.com/ithena-one/mcp-governance-sdk","commit_stats":null,"previous_names":["ithena-one/mcp-governance-sdk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ithena-one%2Fmcp-governance-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ithena-one%2Fmcp-governance-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ithena-one%2Fmcp-governance-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ithena-one%2Fmcp-governance-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ithena-one","download_url":"https://codeload.github.com/ithena-one/mcp-governance-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252804224,"owners_count":21806773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","audit","compliance","credential-manager","credentials","enterprise","governance","identity","identity-management","llm","logging","mcp-server","modelcontextprotocol","open-telemetry","rbac","rbac-management","sdk","tracing","w3c"],"created_at":"2025-05-07T03:15:10.648Z","updated_at":"2025-05-07T03:15:11.097Z","avatar_url":"https://github.com/ithena-one.png","language":"TypeScript","funding_links":[],"categories":["📚 Projects (1974 total)","Products"],"sub_categories":["MCP Servers"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./public/logo-white.png\" alt=\"Ithena Logo\" width=\"200\"\u003e\n\u003c/p\u003e\n\n# MCP Governance SDK (@ithena-one/mcp-governance)\n\n[![NPM Version](https://img.shields.io/npm/v/%40ithena-one%2Fmcp-governance)](https://www.npmjs.com/package/@ithena-one/mcp-governance)\n[![NPM Downloads](https://img.shields.io/npm/dt/@ithena-one/mcp-governance)](https://www.npmjs.com/package/@ithena-one/mcp-governance)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![X Follow](https://img.shields.io/twitter/follow/andellvan?style=social)](https://x.com/andellvan)\n\n\u003ca href=\"https://www.producthunt.com/posts/ithena?embed=true\u0026utm_source=badge-featured\u0026utm_medium=badge\u0026utm_souce=badge-ithena\" target=\"_blank\"\u003e\u003cimg src=\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=948880\u0026theme=light\u0026t=1743628801037\" alt=\"Ithena - AuthN\u0026#0044;\u0026#0032;AuthZ\u0026#0044;\u0026#0032;RBAC\u0026#0044;\u0026#0032;Auditing\u0026#0044;\u0026#0032;\u0026#0038;\u0026#0032;Compliance\u0026#0032;Framework\u0026#0032;for\u0026#0032;MCP | Product Hunt\" style=\"width: 250px; height: 54px;\" width=\"250\" height=\"54\" /\u003e\u003c/a\u003e\n\n\u003c!-- [![Build Status](https://img.shields.io/github/actions/workflow/status/ithena-one/mcp-governance/ci.yml?branch=main)](https://github.com/ithena-one/mcp-governance/actions/workflows/ci.yml) --\u003e\n\u003c!-- Add build status badge once CI is set up --\u003e\n\n**Website:** [ithena.one](https://ithena.one)\n\n**The missing governance layer for your Model Context Protocol (MCP) servers.**\n\nBuild secure, compliant, and observable MCP applications with [Ithena](https://ithena.one). Easily add **Identity, Authorization (RBAC), Credential Management, Auditing, Logging, and Tracing** using our SDK for servers built with [`@modelcontextprotocol/typescript-sdk`](https://github.com/modelcontextprotocol/typescript-sdk), or leverage the upcoming **Ithena Managed Platform** (waitlist open!).\n\n---\n\n**📚 Documentation:**\n\n*   **[Getting Started](./docs/getting-started.md)** - Quick start guide with a complete example\n*   **[Tutorial: Identity \u0026 RBAC](./docs/tutorial.md)** - Step-by-step guide to implementing core governance features\n*   **[Core Concepts](./docs/core-concepts.md)** - Understanding the SDK's architecture and pipeline\n*   **[Configuration](./docs/configuration.md)** - All available options and their usage\n*   **[Interfaces](./docs/interfaces.md)** - Extensibility points and custom implementations\n*   **[Authorization](./docs/authorization.md)** - RBAC system and permission management\n*   **[Auditing \u0026 Logging](./docs/auditing-logging.md)** - Observability and compliance features\n*   **[Default Implementations](./docs/defaults.md)** - Built-in components (development only)\n*   **[Security Considerations](./docs/security.md)** - Security best practices and warnings\n\n---\n\n## The Problem: Production MCP Needs More\n\nThe standard [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) is excellent for implementing the core MCP communication protocol. However, deploying MCP servers in production, especially in enterprise environments, requires addressing critical governance questions:\n\n*   ❓ **Who** is accessing data and tools? (Authentication)\n*   🔒 Are they **allowed** to do that? (Authorization)\n*   🔑 How do handlers securely access needed **secrets**? (Credentials)\n*   📝 **What happened**? (Auditing \u0026 Compliance)\n*   🩺 How do we **monitor and debug** effectively? (Logging \u0026 Tracing)\n\nImplementing these consistently across every MCP server is complex and error-prone.\n\n## The Solution: `@ithena-one/mcp-governance`\n\nThis SDK provides a standard, pluggable framework that wraps the base `Server` class, letting you integrate essential governance features without rewriting your core MCP logic.\n\nIthena offers two ways to achieve this: the **open-source SDK** (`@ithena-one/mcp-governance`) for self-hosting, and the upcoming **Ithena Managed Platform** (currently accepting users via a [waitlist](https://ithena.one#platform)) which provides hosted, production-ready backends for the SDK's interfaces, eliminating infrastructure management.\n\n**Benefits:**\n\n*   ✅ **Standardize Governance:** Consistent handling of identity, permissions, secrets, and auditing.\n*   🔒 **Enhance Security:** Enforce access controls and securely manage credentials.\n*   📝 **Meet Compliance:** Generate detailed audit trails for regulatory requirements.\n*   🧩 **Pluggable Architecture:** Integrate easily with your existing enterprise systems (IDPs, Secret Managers, SIEMs) via well-defined interfaces. (See **[Interfaces](./docs/interfaces.md)**)\n*   ⚙️ **Focus on Business Logic:** Let the SDK handle governance boilerplate, allowing your team to focus on building valuable MCP resources, tools, and prompts.\n*   🚀 **Faster Development:** Get production-ready features out-of-the-box with sensible defaults for development and testing. (See **[Defaults](./docs/defaults.md)**)\n*   ☁️ **Optional Managed Platform:** Skip infrastructure setup and management by using the Ithena Managed Platform (join the [waitlist](https://ithena.one#platform)!).\n\n## Key Features\n\n*   🆔 **Pluggable Identity Resolution** (`IdentityResolver`)\n*   🛡️ **Flexible Role-Based Access Control** (`RoleStore`, `PermissionStore`)\n*   🔑 **Secure Credential Injection** (`CredentialResolver`)\n*   ✍️ **Comprehensive Auditing** (`AuditLogStore`)\n*   🪵 **Structured, Request-Scoped Logging** (`Logger`)\n*   🔗 **Trace Context Propagation** (W3C default via `TraceContextProvider`)\n*   ⚙️ **Configurable Governance Pipeline** (See **[Core Concepts](./docs/core-concepts.md)**)\n*   📦 **Minimal Intrusion** (Wraps the base SDK `Server`)\n\n## Architecture Overview\n\n`@ithena-one/mcp-governance` intercepts incoming MCP requests and notifications, processing them through a defined pipeline before (or during) the execution of your business logic handlers.\n\n```mermaid\ngraph LR\n    A[MCP Request In] --\u003e B(Context Setup: EventID, Logger, TraceContext);\n    B --\u003e C{IdentityResolver?};\n    C -- Yes --\u003e D[Resolve Identity];\n    C -- No --\u003e E[Identity = null];\n    D --\u003e E;\n    E --\u003e F{RBAC Enabled?};\n    F -- No --\u003e K[Credential Resolution];\n    F -- Yes --\u003e G{Identity Resolved?};\n    G -- No --\u003e H(DENY: Identity Required);\n    G -- Yes --\u003e I[Derive Permission];\n    I --\u003e J{Permission Check Needed?};\n    J -- No (null permission) --\u003e L{Post-Auth Hook?};\n    J -- Yes --\u003e J1[Get Roles];\n    J1 --\u003e J2[Check Permissions];\n    J2 -- Denied --\u003e H2(DENY: Insufficient Permission);\n    J2 -- Granted --\u003e L;\n    L -- Yes --\u003e M[Execute Hook];\n    L -- No --\u003e K;\n    M --\u003e K;\n    K -- Yes (Resolver Exists) --\u003e N[Resolve Credentials];\n    K -- No --\u003e O[Credentials = null/undefined];\n    N -- Error \u0026 failOnError=true --\u003e P(FAIL: Credentials Error);\n    N -- Error \u0026 failOnError=false --\u003e O;\n    N -- Success --\u003e O;\n    O --\u003e Q[Execute Governed Handler];\n    Q -- Success --\u003e R[Result];\n    Q -- Error --\u003e S(FAIL: Handler Error);\n    R --\u003e T(Send Response);\n    S --\u003e T;\n    P --\u003e T;\n    H --\u003e T;\n    H2 --\u003e T;\n    T --\u003e U(Audit Log);\n\n    style H fill:#f99,stroke:#333,stroke-width:2px;\n    style H2 fill:#f99,stroke:#333,stroke-width:2px;\n    style P fill:#f99,stroke:#333,stroke-width:2px;\n    style S fill:#f99,stroke:#333,stroke-width:2px;\n    style U fill:#ccf,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;\n```\n\nSee **[Core Concepts](./docs/core-concepts.md)** for more details on the pipeline.\n\nThe SDK defines interfaces (like `IdentityResolver`, `AuditLogStore`, etc.). You can implement these yourself or use clients connecting to the **Ithena Managed Platform** (waitlist open) for a hosted solution.\n\n## SDK vs. Managed Platform\n\nIthena offers flexibility in how you implement MCP governance:\n\n1.  **`@ithena-one/mcp-governance` SDK (Open Source):**\n    *   Provides the core `GovernedServer`, pipeline, and governance interfaces (`IdentityResolver`, `RoleStore`, `AuditLogStore`, etc.).\n    *   You implement the backend logic for these interfaces, integrating with your existing systems (databases, secret managers, SIEMs).\n    *   **Use Case:** Full control over infrastructure, integrating deeply with bespoke internal systems. Requires infrastructure management.\n\n2.  **Ithena Managed Platform (Waitlist Open):**\n    *   A hosted cloud service providing production-ready, scalable backend implementations for the SDK's interfaces via simple API clients.\n    *   Use the same SDK, but configure it to point to the Ithena Platform APIs instead of your own backends.\n    *   **Use Case:** Faster time-to-market, reduced operational burden, focus purely on MCP application logic.\n    *   ➡️ **[Join the Waitlist](https://ithena.one#platform)**\n\nYou choose the approach that best fits your needs. The SDK seamlessly supports both self-hosted and platform-based backends.\n\n## Installation\n\n```bash\nnpm install @ithena-one/mcp-governance @modelcontextprotocol/sdk zod\n# or\nyarn add @ithena-one/mcp-governance @modelcontextprotocol/sdk zod\n# or\npnpm add @ithena-one/mcp-governance @modelcontextprotocol/sdk zod\n```\n\n**Peer Dependencies:** Make sure you have compatible versions of `@modelcontextprotocol/sdk` (check `peerDependencies` in `package.json`) and `zod` installed.\n\n## Quick Start\n\nSee the **[Getting Started Guide](./docs/getting-started.md)** for a runnable example.\n\n## Next Steps\n\n*   Understand the **[Core Concepts](./docs/core-concepts.md)** like `GovernedServer` and the pipeline.\n*   Review the **[Configuration Options](./docs/configuration.md)** available.\n*   Explore the **[Interfaces](./docs/interfaces.md)** to integrate with your systems.\n*   Learn about **[Authorization](./docs/authorization.md)** and **[Auditing/Logging](./docs/auditing-logging.md)**.\n*   Review the **[Security Considerations](./docs/security.md)** carefully.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request on the [GitHub repository](https://github.com/ithena-one/mcp-governance-sdk).\n\n## License\n\nThis project is licensed under the Apache-2.0 License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fithena-one%2Fmcp-governance-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fithena-one%2Fmcp-governance-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fithena-one%2Fmcp-governance-sdk/lists"}