@shivaedev/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShivaeDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @shivaedev/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let AI clients act on application data as the user who connected them. Keep tools in native Effect toolkits, mount them on your application host, and use the same identity and permissions as your contracts.
+
+## Tools for each audience
+
+A signed-in user discovers user tools. An administrator also discovers admin tools. A plain user cannot call a hidden admin tool by guessing its name.
+
+```ts
+const routes = mcpRoutes({
+	name: "My app",
+	version: "1",
+	path: "/mcp",
+	sessions: oauth.sessions,
+	resourceMetadataUrl: oauth.resourceMetadataUrl,
+	audiences: [{ tools: userTools }, { permission: ManageTools.any, tools: adminTools }],
+});
+```
+
+## Using it
+
+Each request authenticates through identity's session policy. The route registers only the caller's permitted audiences with Effect's `McpServer`; discovery and dispatch use that same registry. Handlers receive `Identity` and `SessionUser` from the current request. A shared application Layer never retains a caller's identity.
+
+### Declare native tools and handlers
+
+Use `Tool` and `Toolkit` from `effect/ai`. Declare handler dependencies and failure schemas on the tool, just as contracts declare dependencies and typed failures. Platform does not add another tool definition or handler API.
+
+```ts
+import { Effect, Layer, Schema } from "effect";
+import { McpServer, Tool, Toolkit } from "effect/ai";
+import { permission } from "@shivaedev/access/permission.ts";
+import { role } from "@shivaedev/access/role.ts";
+import { roleSet } from "@shivaedev/access/roleSet.ts";
+import { Identity } from "@shivaedev/identity/identity.ts";
+
+const ManageTools = permission("admin.tools");
+const Roles = roleSet(role("user", []), role("admin", [ManageTools.any]));
+const UserTools = Toolkit.make(
+	Tool.make("whoami", {
+		success: Schema.String,
+		dependencies: [Identity],
+	}),
+);
+const AdminTools = Toolkit.make(
+	Tool.make("adminIdentity", {
+		success: Schema.String,
+		dependencies: [Identity],
+	}),
+);
+const userTools = McpServer.toolkit(UserTools).pipe(
+	Layer.provide(
+		UserTools.toLayer({
+			whoami: () => Effect.map(Identity, ({ id }) => id),
+		}),
+	),
+);
+const adminTools = McpServer.toolkit(AdminTools).pipe(
+	Layer.provide(
+		AdminTools.toLayer({
+			adminIdentity: () => Effect.map(Identity, ({ id }) => id),
+		}),
+	),
+);
+```
+
+Application roles and grants come from `@shivaedev/access`; identity resolves the current stored role and checks those grants. An audience without a permission is available to every signed-in caller. Add `failure: YourErrorSchema` to a tool and return that failure in its Effect handler; native MCP error results carry the declared failure.
+
+### Connect OAuth to identity and the host
+
+The Better Auth adapter is an optional edge module. Add its provider to the auth instance used by identity, alongside Better Auth's JWT plugin. `mcpProvider` configures the `mcp` scope and the endpoint's OAuth resource. The application's login and consent pages implement the provider's ordinary UI flow; the provider owns authorization codes, PKCE and tokens.
+
+```ts
+import { admin, jwt } from "better-auth/plugins";
+import { Effect, Layer } from "effect";
+import { betterAuthMount } from "@shivaedev/identity/server/better-auth/mount.ts";
+import { trustedOrigins } from "@shivaedev/identity/server/origin.ts";
+import { betterAuthMcp, mcpProvider } from "@shivaedev/mcp/adapters/betterAuth.ts";
+import { mcpRoutes } from "@shivaedev/mcp/routes.ts";
+import { appHost } from "@shivaedev/server/appHost.ts";
+
+const application = Effect.gen(function* () {
+	const resource = "https://app.example.com/mcp";
+	const mounted = yield* betterAuthMount(
+		{
+			baseURL: "https://app.example.com",
+			database: authPool,
+			plugins: [
+				jwt(),
+				mcpProvider({
+					resource,
+					loginPage: "/login",
+					consentPage: "/consent",
+					allowDynamicClientRegistration: true,
+					allowUnauthenticatedClientRegistration: true,
+				}),
+			],
+		},
+		{ roles: Roles },
+	);
+	const origin = trustedOrigins({ allow: ["https://app.example.com"], missing: "allow" });
+	const oauth = yield* betterAuthMcp({ auth: mounted.auth, resource, origin, roles: Roles });
+	return appHost({
+		group: Api,
+		handlers: Handlers,
+		sessions: { ...mounted.sessions, origin },
+		routes: Layer.mergeAll(
+			mounted.routes,
+			oauth.routes,
+			mcpRoutes({
+				name: "My app",
+				version: "1",
+				path: "/mcp",
+				sessions: oauth.sessions,
+				resourceMetadataUrl: oauth.resourceMetadataUrl,
+				audiences: [{ tools: userTools }, { permission: ManageTools.any, tools: adminTools }],
+			}),
+		),
+	});
+});
+```
+
+`authPool`, `Api` and `Handlers` are the application's existing auth database, RPC group and handlers. Run the Better Auth migrations with the OAuth and JWT plugins included. For existing role management, keep the application's existing role plugin and `RoleSet` in this configuration.
+
+The edge adapter verifies access-token signatures, issuer, endpoint audience and `mcp` scope, then loads the current user through Better Auth. Identity resolves the stored role on each request. An invalid token receives `401` with a `WWW-Authenticate` protected-resource metadata pointer. The metadata names the authorization server and its discovery endpoint, so a client can start OAuth. MCP bearer credentials are separate from browser session cookies.
+
+### Install and limits
+
+```sh
+pnpm add @shivaedev/mcp effect
+pnpm add better-auth @better-auth/oauth-provider
+```
+
+The OAuth dependencies are optional peers, imported only by `adapters/betterAuth.ts`. Core `routes.ts` also accepts another identity `SessionPolicy` with the same identity and permission semantics.
+
+The endpoint uses Effect's request-scoped Streamable HTTP transport and MCP `2026-07-28`. Clients must support that protocol; earlier session-based versions and subscription streams are outside this adapter. Endpoint requests do not share registries, identities or MCP sessions.

package/dist/adapters/betterAuth.d.ts

@@ -0,0 +1,35 @@
+import { type OAuthOptions, oauthProvider, type Scope } from "@better-auth/oauth-provider";
+import type { AuthContext, BetterAuthOptions } from "better-auth";
+import { Effect } from "effect";
+import { HttpRouter } from "effect/http";
+import type { RoleSet } from "@shivaedev/access/roleSet.ts";
+import { AuthUnavailable } from "@shivaedev/errors/taxonomy.ts";
+import type { OriginPolicy } from "@shivaedev/identity/server/origin.ts";
+import type { SessionPolicy, UserSessionShape } from "@shivaedev/identity/server/session.ts";
+export declare function mcpProvider({ resource, ...options }: Omit<OAuthOptions<Scope[]>, "resources" | "scopes" | "clientRegistrationDefaultResources"> & {
+    readonly resource: string;
+}): ReturnType<typeof oauthProvider>;
+interface OauthAuth {
+    readonly $context: Promise<{
+        readonly internalAdapter: Pick<AuthContext["internalAdapter"], "findUserById">;
+    }>;
+    readonly api: {
+        readonly "getOAuthServerConfig": () => Promise<{
+            readonly issuer: string;
+            readonly "jwks_uri"?: string;
+        }>;
+    };
+    readonly options: BetterAuthOptions;
+}
+export declare const betterAuthMcp: (options: {
+    readonly auth: OauthAuth;
+    readonly resource: string;
+    readonly origin: OriginPolicy;
+    readonly roles?: RoleSet;
+}) => Effect.Effect<{
+    resourceMetadataUrl: string;
+    routes: import("effect/Layer").Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", import("effect/http/HttpServerError").InternalError> | HttpRouter.Request<"Error", import("effect/http/HttpServerError").RequestParseError> | HttpRouter.Request<"Error", import("effect/http/HttpServerError").RouteNotFound>>;
+    sessions: SessionPolicy<UserSessionShape>;
+}, AuthUnavailable, never>;
+export {};
+//# sourceMappingURL=betterAuth.d.ts.map

package/dist/adapters/betterAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"betterAuth.d.ts","sourceRoot":"","sources":["../../src/adapters/betterAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,aAAa,EAAmC,KAAK,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAE5H,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAE7F,wBAAgB,WAAW,CAAC,EAC3B,QAAQ,EACR,GAAG,OAAO,EACV,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,oCAAoC,CAAC,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CACzI,OAAO,aAAa,CACpB,CAEA;AAED,UAAU,SAAS;IAClB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAAE,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,EAAE,cAAc,CAAC,CAAA;KAAE,CAAC,CAAC;IAC/G,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,sBAAsB,EAAE,MAAM,OAAO,CAAC;YAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;IAC5H,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACpC;AAED,eAAO,MAAM,aAAa;mBACV,SAAS;uBACL,MAAM;qBACR,YAAY;qBACZ,OAAO;;;;;0BA0DvB,CAAC"}

package/dist/adapters/betterAuth.js

@@ -0,0 +1,58 @@
+import { oauthProvider, oauthProviderAuthServerMetadata } from "@better-auth/oauth-provider";
+import { oauthProviderResourceClient } from "@better-auth/oauth-provider/resource-client";
+import { Effect, Option } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+import { AuthUnavailable } from "@shivaedev/errors/taxonomy.ts";
+export function mcpProvider({ resource, ...options }) {
+    return oauthProvider({ ...options, clientRegistrationDefaultResources: [resource], resources: [resource], scopes: ["mcp"] });
+}
+export const betterAuthMcp = Effect.fn("Mcp.betterAuthMcp")(function* (options) {
+    const config = yield* Effect.tryPromise({
+        catch: () => new AuthUnavailable({ message: "OAuth provider configuration failed" }),
+        try: () => options.auth.api.getOAuthServerConfig(),
+    });
+    const { auth, resource } = options;
+    const url = new URL(resource);
+    const metadataPath = `/.well-known/oauth-protected-resource${url.pathname}`;
+    const resourceMetadataUrl = new URL(metadataPath, url).href;
+    const client = oauthProviderResourceClient(auth).getActions();
+    const sessions = {
+        origin: options.origin,
+        ...(options.roles === undefined ? {} : { roles: options.roles }),
+        provider: {
+            get: (headers) => Effect.gen(function* () {
+                const authorization = headers.authorization;
+                const token = authorization?.startsWith("Bearer ") ? authorization.slice(7) : undefined;
+                const claims = yield* Effect.tryPromise(() => client.verifyBearerToken(token, {
+                    jwksUrl: config.jwks_uri ?? new URL("/api/auth/jwks", url).href,
+                    requiredScopes: ["mcp"],
+                    verifyOptions: { audience: resource, issuer: config.issuer },
+                })).pipe(Effect.option);
+                if (Option.isNone(claims) || typeof claims.value.sub !== "string") {
+                    return Option.none();
+                }
+                const id = claims.value.sub;
+                const user = yield* Effect.tryPromise({
+                    catch: () => new AuthUnavailable({ message: "OAuth user lookup failed" }),
+                    try: async () => (await auth.$context).internalAdapter.findUserById(id),
+                });
+                if (user === null) {
+                    return Option.none();
+                }
+                const role = Reflect.get(user, "role");
+                return Option.some({ user: { email: user.email, id: user.id, name: user.name, ...(typeof role === "string" ? { role } : {}) } });
+            }),
+        },
+    };
+    const metadata = oauthProviderAuthServerMetadata(auth);
+    const authorizationMetadata = Effect.fn("Mcp.authorizationMetadata")(function* (request) {
+        const web = yield* HttpServerRequest.toWeb(request);
+        return HttpServerResponse.fromWeb(yield* Effect.promise(() => metadata(web)));
+    });
+    const routes = HttpRouter.use((router) => Effect.gen(function* () {
+        yield* router.add("GET", metadataPath, HttpServerResponse.jsonUnsafe({ "authorization_servers": [config.issuer], resource, "scopes_supported": ["mcp"] }));
+        yield* router.add("GET", "/.well-known/oauth-authorization-server/api/auth", authorizationMetadata);
+    }));
+    return { resourceMetadataUrl, routes, sessions };
+});
+//# sourceMappingURL=betterAuth.js.map

package/dist/adapters/betterAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"betterAuth.js","sourceRoot":"","sources":["../../src/adapters/betterAuth.ts"],"names":[],"mappings":"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"}

package/dist/requestServer.d.ts

@@ -0,0 +1,7 @@
+import { Effect } from "effect";
+import { HttpRouter } from "effect/http";
+import { SessionUser } from "@shivaedev/identity/identity.ts";
+import type { UserSessionShape } from "@shivaedev/identity/server/session.ts";
+import type { McpOptions } from "./routes.ts";
+export declare const requestServer: <TSession extends UserSessionShape, E, R>(options: McpOptions<TSession, E, R>) => Effect.Effect<import("effect/http/HttpServerResponse").HttpServerResponse, unknown, import("effect/http/HttpServerRequest").HttpServerRequest | import("effect/Scope").Scope | SessionUser | Exclude<R, HttpRouter.HttpRouter>>;
+//# sourceMappingURL=requestServer.d.ts.map

package/dist/requestServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestServer.d.ts","sourceRoot":"","sources":["../src/requestServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAS,MAAM,QAAQ,CAAC;AAEvC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,aAAa,GAA6C,QAAQ,SAAS,gBAAgB,EAAE,CAAC,EAAE,CAAC,yQAS5G,CAAC"}

package/dist/requestServer.js

@@ -0,0 +1,16 @@
+import { Effect, Layer } from "effect";
+import { McpProtocol, McpServer } from "effect/ai";
+import { HttpRouter } from "effect/http";
+import { SessionUser } from "@shivaedev/identity/identity.ts";
+import { hasPermission } from "@shivaedev/identity/permission.ts";
+export const requestServer = Effect.fn("Mcp.requestServer")(function* (options) {
+    const user = yield* SessionUser;
+    const inner = yield* HttpRouter.make;
+    const transport = McpServer.layerHttpRequestScoped({ ...options, protocols: [McpProtocol.v2026_07_28] });
+    const tools = options.audiences
+        .filter(({ permission }) => permission === undefined || hasPermission(user, permission))
+        .map((audience) => audience.tools);
+    yield* Layer.build(Layer.mergeAll(transport, ...tools)).pipe(Effect.provideService(HttpRouter.HttpRouter, inner));
+    return yield* inner.asHttpEffect();
+});
+//# sourceMappingURL=requestServer.js.map

package/dist/requestServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestServer.js","sourceRoot":"","sources":["../src/requestServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAIlE,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,EAAE,CAAC,mBAAmB,CAAC,CAAC,QAAQ,CAAC,EAA2C,OAAmC;IAClJ,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,WAAW,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;IACrC,MAAM,SAAS,GAAG,SAAS,CAAC,sBAAsB,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACzG,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS;SAC7B,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,UAAU,KAAK,SAAS,IAAI,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;SACvF,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpC,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC;IAClH,OAAO,KAAK,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;AACpC,CAAC,CAAC,CAAC"}

package/dist/routes.d.ts

@@ -0,0 +1,20 @@
+import { type Layer } from "effect";
+import { HttpRouter } from "effect/http";
+import type { Permission } from "@shivaedev/access/permission.ts";
+import type { Identity, SessionUser } from "@shivaedev/identity/identity.ts";
+import { type SessionPolicy, type UserSessionShape } from "@shivaedev/identity/server/session.ts";
+export interface Audience<E = never, R = never> {
+    readonly permission?: Permission;
+    readonly tools: Layer.Layer<never, E, R>;
+}
+export interface McpOptions<TSession extends UserSessionShape, E, R> {
+    readonly allowedOrigins?: readonly string[];
+    readonly audiences: readonly Audience<E, R>[];
+    readonly name: string;
+    readonly path: HttpRouter.PathInput;
+    readonly resourceMetadataUrl: string;
+    readonly sessions: SessionPolicy<TSession>;
+    readonly version: string;
+}
+export declare function mcpRoutes<TSession extends UserSessionShape, E, R>(options: McpOptions<TSession, E, R>): Layer.Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", unknown> | Exclude<HttpRouter.Request.From<"Requires", Exclude<Exclude<Exclude<R, HttpRouter.HttpRouter>, Identity | SessionUser>, HttpRouter.Provided>>, import("effect/Scope").Scope>>;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAsB,MAAM,aAAa,CAAC;AAE7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAmB,MAAM,uCAAuC,CAAC;AAGnH,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,UAAU,CAAC,QAAQ,SAAS,gBAAgB,EAAE,CAAC,EAAE,CAAC;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAaD,wBAAgB,SAAS,CAAC,QAAQ,SAAS,gBAAgB,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,0QAarG"}

package/dist/routes.js

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import * as HttpStatus from "effect/http/HttpStatus";
+import { withSessionUser } from "@shivaedev/identity/server/session.ts";
+import { requestServer } from "./requestServer.js";
+function rejection(error, metadataUrl) {
+    return HttpServerResponse.empty({
+        headers: error._tag === "Unauthorized" ? { "cache-control": "no-store", "www-authenticate": `Bearer resource_metadata="${metadataUrl}"` } : {},
+        status: {
+            AuthUnavailable: HttpStatus.fromLiteral("ServiceUnavailable"),
+            Forbidden: HttpStatus.fromLiteral("Forbidden"),
+            Unauthorized: HttpStatus.fromLiteral("Unauthorized"),
+        }[error._tag],
+    });
+}
+export function mcpRoutes(options) {
+    const server = requestServer(options);
+    return HttpRouter.use((router) => router.add("*", options.path, (request) => Effect.context().pipe(withSessionUser(options.sessions, request.headers, request.url), Effect.matchEffect({
+        onFailure: (error) => Effect.succeed(rejection(error, options.resourceMetadataUrl)),
+        onSuccess: (context) => Effect.provideContext(server, context),
+    }))));
+}
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAc,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAC;AAIrD,OAAO,EAA6C,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACnH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAiBnD,SAAS,SAAS,CAAC,KAAiD,EAAE,WAAmB;IACxF,OAAO,kBAAkB,CAAC,KAAK,CAAC;QAC/B,OAAO,EAAE,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,UAAU,EAAE,kBAAkB,EAAE,6BAA6B,WAAW,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE;QAC9I,MAAM,EAAE;YACP,eAAe,EAAE,UAAU,CAAC,WAAW,CAAC,oBAAoB,CAAC;YAC7D,SAAS,EAAE,UAAU,CAAC,WAAW,CAAC,WAAW,CAAC;YAC9C,YAAY,EAAE,UAAU,CAAC,WAAW,CAAC,cAAc,CAAC;SACpD,CAAC,KAAK,CAAC,IAAI,CAAC;KACb,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAA0C,OAAmC;IACrG,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAChC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CACzC,MAAM,CAAC,OAAO,EAA0B,CAAC,IAAI,CAC5C,eAAe,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAC/D,MAAM,CAAC,WAAW,CAAC;QAClB,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACnF,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC;KAC9D,CAAC,CACF,CACD,CACD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "@shivaedev/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Identity-aware Effect MCP tools mounted on the application host",
+  "keywords": [
+    "effect"
+  ],
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShivaeDev/platform.git",
+    "directory": "packages/mcp"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
+    "README.md"
+  ],
+  "dependencies": {
+    "@shivaedev/access": "0.1.2",
+    "@shivaedev/errors": "0.1.1",
+    "@shivaedev/identity": "0.4.0"
+  },
+  "devDependencies": {
+    "@better-auth/oauth-provider": "1.7.12",
+    "@effect/platform-node": "4.0.6",
+    "@effect/sql-pg": "4.0.6",
+    "@shivaedev/quality": "0.45.0",
+    "@shivaedev/server": "0.5.0",
+    "@shivaedev/test-sql": "0.11.0",
+    "@shivaedev/test-story": "0.24.0",
+    "@types/node": "24.19.2",
+    "better-auth": "1.7.12",
+    "effect": "4.0.6",
+    "pg": "8.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "@better-auth/oauth-provider": "1.7.12",
+    "better-auth": "1.7.12",
+    "effect": "4.0.6"
+  },
+  "peerDependenciesMeta": {
+    "@better-auth/oauth-provider": {
+      "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "quality": {
+    "runtime": "server"
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/adapters/betterAuth.ts

@@ -0,0 +1,88 @@
+import { type OAuthOptions, oauthProvider, oauthProviderAuthServerMetadata, type Scope } from "@better-auth/oauth-provider";
+import { oauthProviderResourceClient } from "@better-auth/oauth-provider/resource-client";
+import type { AuthContext, BetterAuthOptions } from "better-auth";
+import { Effect, Option } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+import type { RoleSet } from "@shivaedev/access/roleSet.ts";
+import { AuthUnavailable } from "@shivaedev/errors/taxonomy.ts";
+import type { OriginPolicy } from "@shivaedev/identity/server/origin.ts";
+import type { SessionPolicy, UserSessionShape } from "@shivaedev/identity/server/session.ts";
+
+export function mcpProvider({
+	resource,
+	...options
+}: Omit<OAuthOptions<Scope[]>, "resources" | "scopes" | "clientRegistrationDefaultResources"> & { readonly resource: string }): ReturnType<
+	typeof oauthProvider
+> {
+	return oauthProvider({ ...options, clientRegistrationDefaultResources: [resource], resources: [resource], scopes: ["mcp"] });
+}
+
+interface OauthAuth {
+	readonly $context: Promise<{ readonly internalAdapter: Pick<AuthContext["internalAdapter"], "findUserById"> }>;
+	readonly api: { readonly "getOAuthServerConfig": () => Promise<{ readonly issuer: string; readonly "jwks_uri"?: string }> };
+	readonly options: BetterAuthOptions;
+}
+
+export const betterAuthMcp = Effect.fn("Mcp.betterAuthMcp")(function* (options: {
+	readonly auth: OauthAuth;
+	readonly resource: string;
+	readonly origin: OriginPolicy;
+	readonly roles?: RoleSet;
+}) {
+	const config = yield* Effect.tryPromise({
+		catch: () => new AuthUnavailable({ message: "OAuth provider configuration failed" }),
+		try: () => options.auth.api.getOAuthServerConfig(),
+	});
+	const { auth, resource } = options;
+	const url = new URL(resource);
+	const metadataPath = `/.well-known/oauth-protected-resource${url.pathname}` as const;
+	const resourceMetadataUrl = new URL(metadataPath, url).href;
+	const client = oauthProviderResourceClient(auth).getActions();
+	const sessions: SessionPolicy<UserSessionShape> = {
+		origin: options.origin,
+		...(options.roles === undefined ? {} : { roles: options.roles }),
+		provider: {
+			get: (headers) =>
+				Effect.gen(function* () {
+					const authorization = headers.authorization;
+					const token = authorization?.startsWith("Bearer ") ? authorization.slice(7) : undefined;
+					const claims = yield* Effect.tryPromise(() =>
+						client.verifyBearerToken(token, {
+							jwksUrl: config.jwks_uri ?? new URL("/api/auth/jwks", url).href,
+							requiredScopes: ["mcp"],
+							verifyOptions: { audience: resource, issuer: config.issuer },
+						}),
+					).pipe(Effect.option);
+					if (Option.isNone(claims) || typeof claims.value.sub !== "string") {
+						return Option.none();
+					}
+					const id = claims.value.sub;
+					const user = yield* Effect.tryPromise({
+						catch: () => new AuthUnavailable({ message: "OAuth user lookup failed" }),
+						try: async () => (await auth.$context).internalAdapter.findUserById(id),
+					});
+					if (user === null) {
+						return Option.none();
+					}
+					const role: unknown = Reflect.get(user, "role");
+					return Option.some({ user: { email: user.email, id: user.id, name: user.name, ...(typeof role === "string" ? { role } : {}) } });
+				}),
+		},
+	};
+	const metadata = oauthProviderAuthServerMetadata(auth);
+	const authorizationMetadata = Effect.fn("Mcp.authorizationMetadata")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const web = yield* HttpServerRequest.toWeb(request);
+		return HttpServerResponse.fromWeb(yield* Effect.promise(() => metadata(web)));
+	});
+	const routes = HttpRouter.use((router) =>
+		Effect.gen(function* () {
+			yield* router.add(
+				"GET",
+				metadataPath,
+				HttpServerResponse.jsonUnsafe({ "authorization_servers": [config.issuer], resource, "scopes_supported": ["mcp"] }),
+			);
+			yield* router.add("GET", "/.well-known/oauth-authorization-server/api/auth", authorizationMetadata);
+		}),
+	);
+	return { resourceMetadataUrl, routes, sessions };
+});

package/src/requestServer.ts

@@ -0,0 +1,18 @@
+import { Effect, Layer } from "effect";
+import { McpProtocol, McpServer } from "effect/ai";
+import { HttpRouter } from "effect/http";
+import { SessionUser } from "@shivaedev/identity/identity.ts";
+import { hasPermission } from "@shivaedev/identity/permission.ts";
+import type { UserSessionShape } from "@shivaedev/identity/server/session.ts";
+import type { McpOptions } from "./routes.ts";
+
+export const requestServer = Effect.fn("Mcp.requestServer")(function* <TSession extends UserSessionShape, E, R>(options: McpOptions<TSession, E, R>) {
+	const user = yield* SessionUser;
+	const inner = yield* HttpRouter.make;
+	const transport = McpServer.layerHttpRequestScoped({ ...options, protocols: [McpProtocol.v2026_07_28] });
+	const tools = options.audiences
+		.filter(({ permission }) => permission === undefined || hasPermission(user, permission))
+		.map((audience) => audience.tools);
+	yield* Layer.build(Layer.mergeAll(transport, ...tools)).pipe(Effect.provideService(HttpRouter.HttpRouter, inner));
+	return yield* inner.asHttpEffect();
+});

package/src/routes.ts

@@ -0,0 +1,49 @@
+import { Effect, type Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import * as HttpStatus from "effect/http/HttpStatus";
+import type { Permission } from "@shivaedev/access/permission.ts";
+import type { AuthUnavailable, Forbidden, Unauthorized } from "@shivaedev/errors/taxonomy.ts";
+import type { Identity, SessionUser } from "@shivaedev/identity/identity.ts";
+import { type SessionPolicy, type UserSessionShape, withSessionUser } from "@shivaedev/identity/server/session.ts";
+import { requestServer } from "./requestServer.ts";
+
+export interface Audience<E = never, R = never> {
+	readonly permission?: Permission;
+	readonly tools: Layer.Layer<never, E, R>;
+}
+
+export interface McpOptions<TSession extends UserSessionShape, E, R> {
+	readonly allowedOrigins?: readonly string[];
+	readonly audiences: readonly Audience<E, R>[];
+	readonly name: string;
+	readonly path: HttpRouter.PathInput;
+	readonly resourceMetadataUrl: string;
+	readonly sessions: SessionPolicy<TSession>;
+	readonly version: string;
+}
+
+function rejection(error: AuthUnavailable | Forbidden | Unauthorized, metadataUrl: string) {
+	return HttpServerResponse.empty({
+		headers: error._tag === "Unauthorized" ? { "cache-control": "no-store", "www-authenticate": `Bearer resource_metadata="${metadataUrl}"` } : {},
+		status: {
+			AuthUnavailable: HttpStatus.fromLiteral("ServiceUnavailable"),
+			Forbidden: HttpStatus.fromLiteral("Forbidden"),
+			Unauthorized: HttpStatus.fromLiteral("Unauthorized"),
+		}[error._tag],
+	});
+}
+
+export function mcpRoutes<TSession extends UserSessionShape, E, R>(options: McpOptions<TSession, E, R>) {
+	const server = requestServer(options);
+	return HttpRouter.use((router) =>
+		router.add("*", options.path, (request) =>
+			Effect.context<Identity | SessionUser>().pipe(
+				withSessionUser(options.sessions, request.headers, request.url),
+				Effect.matchEffect({
+					onFailure: (error) => Effect.succeed(rejection(error, options.resourceMetadataUrl)),
+					onSuccess: (context) => Effect.provideContext(server, context),
+				}),
+			),
+		),
+	);
+}