@funmary/mcp 0.0.0-reserved → 1.0.0

package/README.md

@@ -0,0 +1,44 @@
+# @funmary/mcp
+
+[Funmary](https://github.com/funmary-app/funmary) の MCP サーバーです。手元のパソコンで動かして、Claude Desktop などから、自分の時間割、休講、予定、バスの時刻表を読み書きできます。Funmary は、公立はこだて未来大学の学生向けの、非公式のアプリです。
+
+## 使い方
+
+Funmary の設定画面で、個人用のアクセストークンを発行し、クライアントの設定に書きます。
+
+```json
+{
+  "mcpServers": {
+    "funmary": {
+      "command": "npx",
+      "args": ["-y", "@funmary/mcp"],
+      "env": {
+        "FUNMARY_URL": "https://funmary.example.com",
+        "FUNMARY_TOKEN": "fmy_..."
+      }
+    }
+  }
+}
+```
+
+- `FUNMARY_URL`: 使っている Funmary のサーバーの URL。既定値は持ちません
+- `FUNMARY_TOKEN`: 個人用のアクセストークン。トークンに許した範囲 (`read:lessons`、`write:events` など) の道具だけが出ます。書き込みの範囲は、必要なときだけ許してください
+
+道具の定義は、Funmary のサーバーの `/mcp` と共有しています。サーバーの `/mcp` に、OAuth で直接つなぐこともできます。
+
+## ライブラリとして
+
+```ts
+import { createFunmaryMcpServer, createClientData } from '@funmary/mcp';
+import { createFunmaryClient } from '@funmary/client';
+
+const client = createFunmaryClient({ baseURL, token });
+const server = createFunmaryMcpServer({
+  data: createClientData(client),
+  scopes: (await client.me()).scopes,
+});
+```
+
+## ライセンス
+
+BSD-3-Clause または Apache-2.0 (好きな方を選べます)。

package/dist/LICENSE-APACHE-2.0

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/LICENSE-BSD-3-CLAUSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, otoneko. a.k.a. marron., oto-lab, and Funmary (funmary-app)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/bin.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { t as runStdioServer } from "./stdio-CHgt2MDi.js";
+//#region src/bin.ts
+const baseURL = process.env["FUNMARY_URL"];
+const token = process.env["FUNMARY_TOKEN"];
+if (!baseURL || !token) {
+	console.error("環境変数 FUNMARY_URL (Funmary のサーバーの URL) と FUNMARY_TOKEN (個人用のアクセストークン) を設定してください");
+	process.exit(1);
+}
+runStdioServer({
+	baseURL,
+	token
+}).catch((error) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+import { FunmaryClient } from "@funmary/client";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+//#region src/data.d.ts
+/** 公開 API と同じ形の JSON */
+type Json = object;
+interface DateRange {
+  readonly start: string;
+  readonly end: string;
+}
+/** 科目の指し方。年度とシラバスの番号か、名前 (年度を省くと、今年度) */
+type CourseRef = {
+  readonly academicYear: number;
+  readonly syllabusId: string;
+} | {
+  readonly name: string;
+  readonly academicYear?: number | undefined;
+};
+interface FunmaryData {
+  timetable(range: DateRange): Promise<Json>;
+  week(query: {
+    date?: string | undefined;
+  }): Promise<Json>;
+  nextLesson(): Promise<Json>;
+  periods(): Promise<readonly Json[]>;
+  courses(): Promise<readonly Json[]>;
+  academicCalendar(query: {
+    year?: number | undefined;
+  }): Promise<Json>;
+  events(range: DateRange): Promise<readonly Json[]>;
+  event(id: number): Promise<Json | null>;
+  status(): Promise<Json>;
+  searchSubjects(query: {
+    q?: string | undefined;
+    year?: number | undefined;
+    term?: string | undefined;
+  }): Promise<Json>;
+  subjectSessions(ref: {
+    year: number;
+    syllabusId: string;
+  }): Promise<Json | null>;
+  subject(ref: {
+    year: number;
+    syllabusId: string;
+  }): Promise<Json | null>;
+  notifications(query: {
+    limit?: number | undefined;
+    afterId?: number | undefined;
+  }): Promise<readonly Json[]>;
+  busStops(): Promise<Json | null>;
+  busStopTimetable(stopId: string, generation?: number): Promise<Json | null>;
+  busLeg(query: {
+    stopId: string;
+    direction: 'toUniversity' | 'fromUniversity';
+    day?: 'weekday' | 'holiday' | undefined;
+    limit?: number | undefined;
+  }): Promise<Json | null>;
+  busNext(query: {
+    stopId?: string | undefined;
+    limit?: number | undefined;
+  }): Promise<Json | null>;
+  createEvent(body: unknown): Promise<Json>;
+  replaceEvent(id: number, body: unknown): Promise<Json>;
+  deleteEvent(id: number): Promise<void>;
+  registerCourse(ref: CourseRef): Promise<Json>;
+  unregisterCourse(ref: CourseRef): Promise<Json>;
+  setPersonalSlot(ref: CourseRef, slot: {
+    weekday: number;
+    period: number;
+    room?: string | null | undefined;
+  }): Promise<Json>;
+  removePersonalSlot(ref: CourseRef, slot: {
+    weekday: number;
+    period: number;
+  }): Promise<Json>;
+  setAbbreviation(ref: CourseRef, abbreviation: string): Promise<Json>;
+  markNotificationRead(id: number): Promise<Json>;
+  markAllNotificationsRead(): Promise<Json>;
+}
+/** 書き込みや読み取りの失敗。文は、そのまま、利用者 (と AI) に見せる */
+export declare class FunmaryToolFailure extends Error {
+  constructor(message: string);
+}
+/** 名前が複数の科目に当たったときの、候補つきの文 (道具の答えと、手元の MCP の両方で同じにする) */
+export declare function ambiguousMessage(error: string, candidates: readonly {
+  academicYear: number;
+  syllabusId: string;
+  name: string;
+}[]): string;
+//#endregion
+//#region src/client-data.d.ts
+export declare function createClientData(client: FunmaryClient): FunmaryData;
+//#endregion
+//#region src/tools.d.ts
+interface ToolContext {
+  readonly data: FunmaryData;
+  /** いまの時刻 (省くと「今日」を決めるのに使う)。テストで差し替える */
+  readonly now: () => Date;
+}
+type ToolOutput = {
+  readonly kind: 'json';
+  readonly value: object;
+} | {
+  readonly kind: 'error';
+  readonly message: string;
+};
+interface ToolAnnotations {
+  readonly readOnlyHint: boolean;
+  readonly destructiveHint?: boolean;
+  readonly idempotentHint?: boolean;
+}
+interface ToolDefinition<Shape extends z.ZodRawShape = z.ZodRawShape> {
+  readonly name: string;
+  /** アクセストークンの範囲 (read:lessons など)。この範囲を持つときだけ、道具を出す */
+  readonly scope: string;
+  readonly description: string;
+  readonly inputSchema?: Shape;
+  readonly annotations: ToolAnnotations;
+  run(context: ToolContext, args: z.infer<z.ZodObject<Shape>>): Promise<ToolOutput>;
+}
+/** すべての道具。出す順は、読み取り、書き込みの順 */
+export declare const TOOLS: readonly ToolDefinition[];
+/** 道具の処理で起きた失敗を、利用者に見せる文にする。想定外の例外は、そのまま投げる */
+export declare function failureMessage(caught: unknown): string | null;
+//#endregion
+//#region src/server.d.ts
+interface RegisterToolsOptions {
+  readonly data: FunmaryData;
+  /** トークンに許された範囲。この範囲の道具だけを出す */
+  readonly scopes: readonly string[];
+  /** 範囲があっても、出さない道具を決める (例: バスの機能を使わないサーバーで、バスの道具を出さない) */
+  readonly enabled?: (tool: ToolDefinition) => boolean;
+  readonly now?: () => Date;
+}
+/** 範囲に合う道具を、サーバーに登録する。登録した道具の名前を返す */
+export declare function registerTools(server: McpServer, options: RegisterToolsOptions): string[];
+interface CreateMcpServerOptions extends RegisterToolsOptions {
+  readonly name?: string;
+  readonly version?: string;
+  readonly icons?: readonly {
+    src: string;
+    mimeType?: string;
+    sizes?: string[];
+    theme?: 'light' | 'dark';
+  }[];
+}
+/** 道具を登録した MCP サーバーを作る */
+export declare function createFunmaryMcpServer(options: CreateMcpServerOptions): McpServer;
+//#endregion
+//#region src/stdio.d.ts
+interface StdioOptions {
+  /** Funmary のサーバーの URL (既定値は持たない) */
+  readonly baseURL: string;
+  /** 設定画面で発行した、個人用のアクセストークン */
+  readonly token: string;
+  readonly version?: string;
+}
+/** サーバーを起動して、標準入出力に結ぶ。トークンが使えなければ、理由の分かる文で、例外にする */
+export declare function runStdioServer(options: StdioOptions): Promise<void>;
+//#endregion
+export type { CourseRef, CreateMcpServerOptions, DateRange, FunmaryData, Json, RegisterToolsOptions, StdioOptions, ToolAnnotations, ToolContext, ToolDefinition, ToolOutput };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as failureMessage, c as ambiguousMessage, i as TOOLS, n as createFunmaryMcpServer, o as createClientData, r as registerTools, s as FunmaryToolFailure, t as runStdioServer } from "./stdio-CHgt2MDi.js";
+export { FunmaryToolFailure, TOOLS, ambiguousMessage, createClientData, createFunmaryMcpServer, failureMessage, registerTools, runStdioServer };

package/dist/stdio-CHgt2MDi.js

@@ -0,0 +1,689 @@
+import { FunmaryApiError, createFunmaryClient } from "@funmary/client";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+//#region src/data.ts
+/** 書き込みや読み取りの失敗。文は、そのまま、利用者 (と AI) に見せる */
+var FunmaryToolFailure = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "FunmaryToolFailure";
+	}
+};
+/** 名前が複数の科目に当たったときの、候補つきの文 (道具の答えと、手元の MCP の両方で同じにする) */
+function ambiguousMessage(error, candidates) {
+	return `${error}: ${candidates.map((c) => `${c.academicYear} ${c.syllabusId} ${c.name}`).join(" / ")}`;
+}
+//#endregion
+//#region src/client-data.ts
+/** 404 を「見つからない」(null) にする。ほかの誤りは、そのまま投げる */
+async function orNull(read) {
+	try {
+		return await read;
+	} catch (error) {
+		if (error instanceof FunmaryApiError && error.status === 404) return null;
+		throw error;
+	}
+}
+function createClientData(client) {
+	/**
+	* 書き込みの API は、年度とシラバスの番号で科目を指す。名前で指されたときは、科目の検索で、番号に直す。
+	* 完全に一致する科目が 1 つならそれを、なければ部分一致が 1 つならそれを選び、複数なら、候補つきで断る
+	*/
+	async function resolve(ref) {
+		if ("syllabusId" in ref) return {
+			year: ref.academicYear,
+			syllabusId: ref.syllabusId
+		};
+		const needle = ref.name.trim().toLowerCase();
+		const found = (await client.subjects.search({
+			q: ref.name,
+			year: ref.academicYear
+		})).subjects;
+		const exact = found.filter((subject) => subject.name.trim().toLowerCase() === needle);
+		const matched = exact.length > 0 ? exact : found;
+		const [only] = matched;
+		if (matched.length === 1 && only) return {
+			year: only.academicYear,
+			syllabusId: only.syllabusId
+		};
+		if (matched.length === 0) throw new FunmaryToolFailure("科目が見つかりません");
+		throw new FunmaryToolFailure(ambiguousMessage(`「${ref.name}」に当たる科目が ${matched.length} 件あります。年度とシラバスの番号で指してください`, matched.toSorted((a, b) => a.syllabusId.localeCompare(b.syllabusId)).slice(0, 10)));
+	}
+	return {
+		timetable: (range) => client.timetable(range),
+		week: (query) => client.week(query.date === void 0 ? {} : { date: query.date }),
+		nextLesson: () => client.nextLesson(),
+		periods: () => client.periods(),
+		courses: () => client.courses.list(),
+		academicCalendar: (query) => client.academicCalendar(query.year === void 0 ? {} : { year: query.year }),
+		events: (range) => client.events.list(range),
+		event: (id) => orNull(client.events.get(id)),
+		status: () => client.status(),
+		searchSubjects: (query) => client.subjects.search(query),
+		subjectSessions: (ref) => orNull(client.subjects.sessions(ref)),
+		subject: (ref) => orNull(client.subjects.get(ref)),
+		notifications: (query) => client.notifications.list(query),
+		busStops: () => orNull(client.bus.stops()),
+		busStopTimetable: (stopId, generation) => orNull(client.bus.stop(stopId, generation === void 0 ? {} : { generation })),
+		busLeg: (query) => orNull(client.bus.legs({
+			stopId: query.stopId,
+			direction: query.direction,
+			...query.day === void 0 ? {} : { day: query.day },
+			...query.limit === void 0 ? {} : { limit: query.limit }
+		})),
+		busNext: (query) => orNull(client.bus.next({
+			...query.stopId === void 0 ? {} : { stopId: query.stopId },
+			...query.limit === void 0 ? {} : { limit: query.limit }
+		})),
+		createEvent: (body) => client.events.create(body),
+		replaceEvent: (id, body) => client.events.replace(id, body),
+		deleteEvent: (id) => client.events.delete(id).then(() => void 0),
+		registerCourse: (ref) => client.courses.register("syllabusId" in ref ? {
+			academicYear: ref.academicYear,
+			syllabusId: ref.syllabusId
+		} : {
+			name: ref.name,
+			...ref.academicYear === void 0 ? {} : { academicYear: ref.academicYear }
+		}),
+		unregisterCourse: async (ref) => client.courses.unregister(await resolve(ref)),
+		setPersonalSlot: async (ref, slot) => client.courses.setPersonalSlot(await resolve(ref), {
+			weekday: slot.weekday,
+			period: slot.period,
+			room: slot.room ?? null
+		}),
+		removePersonalSlot: async (ref, slot) => client.courses.removePersonalSlot(await resolve(ref), slot),
+		setAbbreviation: async (ref, abbreviation) => client.courses.setAbbreviation(await resolve(ref), abbreviation),
+		markNotificationRead: (id) => client.notifications.markRead(id),
+		markAllNotificationsRead: () => client.notifications.markAllRead()
+	};
+}
+//#endregion
+//#region src/tools.ts
+const json = (value) => ({
+	kind: "json",
+	value
+});
+const error = (message) => ({
+	kind: "error",
+	message
+});
+const orNotFound = (value) => json(value ?? { error: "not_found" });
+/** 日本時間の今日の日付 (YYYY-MM-DD) */
+const todayJst = (now) => new Date(now.getTime() + 324e5).toISOString().slice(0, 10);
+const READ = { readOnlyHint: true };
+function define(tool) {
+	return tool;
+}
+const readLessons = [
+	define({
+		name: "get_lessons",
+		scope: "read:lessons",
+		description: "日付 (YYYY-MM-DD、日本時間) か期間の授業を、開始と終了の時刻つきで返す (日付を省くと今日)。days に、振替授業日 (その日に行う授業の曜日)、全学の休講日、祝日が入る。status は normal (変更なし)、cancelled (休講)、makeup (補講)、roomChanged (教室変更)。room が null なら教室は分からず、roomIsTentative が true なら補講の教室を、ふだんの教室で仮に出している",
+		inputSchema: {
+			start: z.string().optional(),
+			end: z.string().optional()
+		},
+		annotations: READ,
+		async run({ data, now }, { start, end }) {
+			const today = todayJst(now());
+			return json(await data.timetable({
+				start: start ?? today,
+				end: end ?? start ?? today
+			}));
+		}
+	}),
+	define({
+		name: "get_week",
+		scope: "read:lessons",
+		description: "date (YYYY-MM-DD、日本時間。省くと今日) を含む週 (月曜から日曜) の、曜日と時限の格子。授業のない時限も cells に入る (lessons が空)。振替授業日などは note に入る",
+		inputSchema: { date: z.string().optional() },
+		annotations: READ,
+		async run({ data, now }, { date }) {
+			return json(await data.week({ date: date ?? todayJst(now()) }));
+		}
+	}),
+	define({
+		name: "get_next_lesson",
+		scope: "read:lessons",
+		description: "今の時刻から見た、次の授業を返す。授業中ならその授業 (inProgress が true)。休講の授業は飛ばし、14 日先まで見て、なければ next が null",
+		annotations: READ,
+		async run({ data }) {
+			return json(await data.nextLesson());
+		}
+	}),
+	define({
+		name: "get_periods",
+		scope: "read:lessons",
+		description: "時限ごとの開始と終了の時刻 (日本時間)",
+		annotations: READ,
+		async run({ data }) {
+			return json({ periods: await data.periods() });
+		}
+	}),
+	define({
+		name: "list_courses",
+		scope: "read:lessons",
+		description: "履修登録した科目と、その曜日 (1 が月曜から 7 が日曜) と時限",
+		annotations: READ,
+		async run({ data }) {
+			return json({ courses: await data.courses() });
+		}
+	}),
+	define({
+		name: "get_academic_calendar",
+		scope: "read:lessons",
+		description: "年度の学期の期間と、その年度の祝日、全学の休講日、振替授業日を返す (年度を省くと今日が属する年度)",
+		inputSchema: { year: z.number().optional() },
+		annotations: READ,
+		async run({ data }, { year }) {
+			return json(await data.academicCalendar({ year }));
+		}
+	}),
+	define({
+		name: "list_events",
+		scope: "read:lessons",
+		description: "日付 (YYYY-MM-DD、日本時間) の範囲の、自分の予定と、時間割に加えたほかの人の予定 (繰り返しは回ごとに展開)。日付を省くと今日",
+		inputSchema: {
+			start: z.string().optional(),
+			end: z.string().optional()
+		},
+		annotations: READ,
+		async run({ data, now }, { start, end }) {
+			const today = todayJst(now());
+			return json({ events: await data.events({
+				start: start ?? today,
+				end: end ?? start ?? today
+			}) });
+		}
+	}),
+	define({
+		name: "get_event",
+		scope: "read:lessons",
+		description: "自分の予定を 1 件、update_event に送り直せる形で返す。繰り返しや除く日も入る。ほかの人の予定は、見つからないことにする",
+		inputSchema: { id: z.number().describe("予定の id (list_events の eventId)") },
+		annotations: READ,
+		async run({ data }, { id }) {
+			const event = await data.event(id);
+			return event ? json(event) : error("予定が見つかりません");
+		}
+	}),
+	define({
+		name: "get_data_status",
+		scope: "read:lessons",
+		description: "休講や教室の変更のデータが新しいか。stale が true のときは、反映が遅れているかもしれないので、授業の答えに添える",
+		annotations: READ,
+		async run({ data }) {
+			return json(await data.status());
+		}
+	}),
+	define({
+		name: "search_subjects",
+		scope: "read:lessons",
+		description: "年度 (省けば今年度) の科目を、名前、教員、授業コードで探す。公開の科目だけを 50 件まで返す。term は spring、fall など",
+		inputSchema: {
+			q: z.string().max(100).optional(),
+			year: z.number().optional(),
+			term: z.string().optional()
+		},
+		annotations: READ,
+		async run({ data }, query) {
+			return json(await data.searchSubjects(query));
+		}
+	}),
+	define({
+		name: "get_subject_sessions",
+		scope: "read:lessons",
+		description: "科目のその年度の全授業日 (時刻、教室、休講、補講、教室変更を反映)。sequence は休講を除いた通し番号で、シラバスの第 n 回とは限らない",
+		inputSchema: {
+			year: z.number(),
+			syllabusId: z.string()
+		},
+		annotations: READ,
+		async run({ data }, ref) {
+			return orNotFound(await data.subjectSessions(ref));
+		}
+	}),
+	define({
+		name: "get_subject",
+		scope: "read:lessons",
+		description: "授業の詳細を返す",
+		inputSchema: {
+			year: z.number(),
+			syllabusId: z.string()
+		},
+		annotations: READ,
+		async run({ data }, ref) {
+			return orNotFound(await data.subject(ref));
+		}
+	}),
+	define({
+		name: "list_changes",
+		scope: "read:changes",
+		description: "日付 (YYYY-MM-DD、日本時間) の範囲の休講、補講、教室変更を返す。days に、その期間の振替授業日、全学の休講日、祝日も入る",
+		inputSchema: {
+			start: z.string(),
+			end: z.string()
+		},
+		annotations: READ,
+		async run({ data }, { start, end }) {
+			const { lessons, days } = await data.timetable({
+				start,
+				end
+			});
+			return json({
+				changes: lessons.filter((lesson) => lesson.status !== "normal"),
+				days
+			});
+		}
+	}),
+	define({
+		name: "list_notifications",
+		scope: "read:notifications",
+		description: "通知欄 (休講、補講、教室変更などの知らせ) を、新しい順に返す。前回読んだ最大の id を afterId に渡すと、それより新しいものだけを返すので、定期的な確認に使える",
+		inputSchema: {
+			limit: z.number().optional(),
+			afterId: z.number().optional()
+		},
+		annotations: READ,
+		async run({ data }, query) {
+			return json({ notifications: await data.notifications(query) });
+		}
+	})
+];
+const readTransit = [
+	define({
+		name: "list_bus_stops",
+		scope: "read:transit",
+		description: "バスの停留所と、時刻表の版 (ダイヤ改正ごと) の一覧。highlighted が true の停留所は、既定で強調する停留所 (未来大、亀田支所前)。まだ取り込んでいなければ stops が空",
+		annotations: READ,
+		async run({ data }) {
+			return json(await data.busStops() ?? { error: "not_available" });
+		}
+	}),
+	define({
+		name: "get_bus_stop_timetable",
+		scope: "read:transit",
+		description: "1 つの停留所の発車表。のりばと曜日の区分 (weekday は平日、holiday は土曜、日曜、祝日) ごとに分かれ、発車の time は HH:MM (日本時間、24 時以降は 24:10 のように書く)。notes に印の意味がある。generation (8 桁の版のコード) を省くと、今日に有効な版",
+		inputSchema: {
+			stopId: z.string(),
+			generation: z.number().optional()
+		},
+		annotations: READ,
+		async run({ data }, { stopId, generation }) {
+			return orNotFound(await data.busStopTimetable(stopId, generation));
+		}
+	}),
+	define({
+		name: "get_bus_leg",
+		scope: "read:transit",
+		description: "「A から未来大へ」「未来大から A へ」のバスの発車。stopId は、未来大を通る任意の停留所 A (list_bus_stops で探す)。direction は toUniversity (A から未来大) か fromUniversity (未来大から A)。departures はその日の区分の全部、upcoming はこれからの発車。向きは、時刻表の経由と行き先の文字から決めるので、経由に書かれない停留所を通る便は、出ないことがある。day (weekday か holiday) を省くと今日の区分",
+		inputSchema: {
+			stopId: z.string(),
+			direction: z.enum(["toUniversity", "fromUniversity"]),
+			day: z.enum(["weekday", "holiday"]).optional(),
+			limit: z.number().optional()
+		},
+		annotations: READ,
+		async run({ data }, query) {
+			return orNotFound(await data.busLeg(query));
+		}
+	}),
+	define({
+		name: "get_next_buses",
+		scope: "read:transit",
+		description: "今から先のバスの発車を、停留所ごとに近い順に返す (土曜、日曜、祝日は休日の発車表)。stopId を省くと、強調する停留所 (未来大、亀田支所前)。limit は停留所ごとの件数 (既定 3)。minutesUntil は発車までの分",
+		inputSchema: {
+			stopId: z.string().optional(),
+			limit: z.number().optional()
+		},
+		annotations: READ,
+		async run({ data }, query) {
+			return orNotFound(await data.busNext(query));
+		}
+	})
+];
+/** 予定の項目。足すときと直すときで同じ (REST の本文と同じ形) */
+const eventShape = {
+	title: z.string().describe("予定の名前 (100 文字まで)"),
+	location: z.string().nullable().optional().describe("場所 (100 文字まで)"),
+	notes: z.string().nullable().optional().describe("メモ (1000 文字まで)"),
+	startDate: z.string().describe("開始日 (YYYY-MM-DD)"),
+	endDate: z.string().nullable().optional().describe("終了日 (YYYY-MM-DD)。省けば開始日と同じ。数日にわたる予定は終日だけ"),
+	time: z.discriminatedUnion("kind", [
+		z.object({ kind: z.literal("allDay") }),
+		z.object({
+			kind: z.literal("time"),
+			start: z.string().describe("HH:MM (日本時間)"),
+			end: z.string().describe("HH:MM。始まりより後")
+		}),
+		z.object({
+			kind: z.literal("period"),
+			from: z.number().describe("始まりの時限 (1 から 6)"),
+			to: z.number().describe("終わりの時限 (始まり以上、6 まで)")
+		})
+	]).describe("終日、時刻、時限のどれか"),
+	repeat: z.object({
+		freq: z.enum([
+			"daily",
+			"weekly",
+			"monthly",
+			"yearly"
+		]),
+		interval: z.number().optional().describe("間隔 (1 から 99)。省けば 1"),
+		weekdays: z.array(z.number()).optional().describe("weekly のとき。曜日 (月曜が 1、日曜が 7)。省けば開始日の曜日"),
+		monthly: z.enum([
+			"day",
+			"nth",
+			"last"
+		]).optional().describe("monthly のとき。day は毎月の同じ日、nth は第何曜日、last は最終週の曜日"),
+		end: z.discriminatedUnion("kind", [
+			z.object({ kind: z.literal("never") }),
+			z.object({
+				kind: z.literal("until"),
+				date: z.string()
+			}),
+			z.object({
+				kind: z.literal("count"),
+				count: z.number()
+			})
+		]).optional().describe("省けば、終わりなし")
+	}).nullable().optional().describe("繰り返さないなら省くか null"),
+	excludedDates: z.array(z.string()).optional().describe("繰り返しから除く日 (YYYY-MM-DD。始まりの日で数える)")
+};
+/** 履修の道具が、科目を指すための項目 */
+const courseRefShape = {
+	academicYear: z.number().optional().describe("年度 (例: 2026)。name で指すときは省ける"),
+	syllabusId: z.string().optional().describe("シラバスの番号 (授業コード)"),
+	name: z.string().optional().describe("科目名。syllabusId を省くときに使う")
+};
+/** 引数から、科目の指し方を決める。足りなければ、利用者に伝える文を返す */
+function refOf(args) {
+	if (args.syllabusId !== void 0) return args.academicYear === void 0 ? { error: "syllabusId で指すときは、academicYear (年度) も必要です" } : { ref: {
+		academicYear: args.academicYear,
+		syllabusId: args.syllabusId
+	} };
+	if (args.name !== void 0) return { ref: {
+		name: args.name,
+		academicYear: args.academicYear
+	} };
+	return { error: "科目を、academicYear と syllabusId か、name で指してください" };
+}
+const slotShape = {
+	weekday: z.number().describe("曜日 (1 が月曜から 6 が土曜)"),
+	period: z.number().describe("時限 (1 から 6)")
+};
+const writeEvents = [
+	define({
+		name: "create_event",
+		scope: "write:events",
+		description: "自分の予定を足す。公開範囲は決められず、常に非公開で足す。足した予定 (id つき) を返す。1 分あたり 20 回まで",
+		inputSchema: eventShape,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		},
+		async run({ data }, args) {
+			return json(await data.createEvent(args));
+		}
+	}),
+	define({
+		name: "update_event",
+		scope: "write:events",
+		description: "自分の予定を、送った内容に置き換える (送らなかった項目は、空になる)。先に get_event で今の内容を読み、変える項目だけを書き換えて送る。公開範囲は変わらない",
+		inputSchema: {
+			id: z.number().describe("予定の id"),
+			...eventShape
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		},
+		async run({ data }, { id, ...rest }) {
+			return json(await data.replaceEvent(id, rest));
+		}
+	}),
+	define({
+		name: "delete_event",
+		scope: "write:events",
+		description: "自分の予定を消す。元には戻せないので、消す前に、利用者に確かめる",
+		inputSchema: { id: z.number().describe("予定の id") },
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		},
+		async run({ data }, { id }) {
+			await data.deleteEvent(id);
+			return json({
+				deleted: true,
+				id
+			});
+		}
+	})
+];
+const writeCourses = [
+	define({
+		name: "register_course",
+		scope: "write:courses",
+		description: "履修登録する。科目は、academicYear (年度) と syllabusId (シラバスの番号) か、name (科目名。年度を省くと今年度) で指す。name が複数の科目に当たったら、登録せず候補を返すので、利用者に確かめて、番号で指し直す。登録済みなら、何も変えずに今の状態を返す",
+		inputSchema: courseRefShape,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		},
+		async run({ data }, args) {
+			const target = refOf(args);
+			return "error" in target ? error(target.error) : json(await data.registerCourse(target.ref));
+		}
+	}),
+	define({
+		name: "unregister_course",
+		scope: "write:courses",
+		description: "履修登録を取り消す。自分だけの曜日と時限と略称は残るので、登録し直せば元に戻る。取り消す前に、利用者に確かめる",
+		inputSchema: courseRefShape,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		},
+		async run({ data }, args) {
+			const target = refOf(args);
+			return "error" in target ? error(target.error) : json(await data.unregisterCourse(target.ref));
+		}
+	}),
+	define({
+		name: "set_personal_slot",
+		scope: "write:courses",
+		description: "自分だけに使う曜日と時限を足す (同じ曜日と時限があれば、教室を上書きする)。ほかの利用者の時間割には効かない。履修登録した科目だけ。共有の枠は、ここからは書き込めない",
+		inputSchema: {
+			...courseRefShape,
+			...slotShape,
+			room: z.string().nullable().optional().describe("教室 (100 文字まで)。省くと空")
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		},
+		async run({ data }, { weekday, period, room, ...refArgs }) {
+			const target = refOf(refArgs);
+			return "error" in target ? error(target.error) : json(await data.setPersonalSlot(target.ref, {
+				weekday,
+				period,
+				room
+			}));
+		}
+	}),
+	define({
+		name: "remove_personal_slot",
+		scope: "write:courses",
+		description: "自分だけの曜日と時限を消す",
+		inputSchema: {
+			...courseRefShape,
+			...slotShape
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		},
+		async run({ data }, { weekday, period, ...refArgs }) {
+			const target = refOf(refArgs);
+			return "error" in target ? error(target.error) : json(await data.removePersonalSlot(target.ref, {
+				weekday,
+				period
+			}));
+		}
+	}),
+	define({
+		name: "set_subject_abbreviation",
+		scope: "write:courses",
+		description: "時間割のセルに出す、自分だけの略称を保存する (100 文字まで)。空にすると、正式名称を使う指定になる",
+		inputSchema: {
+			...courseRefShape,
+			abbreviation: z.string().describe("略称。空文字で、正式名称に戻す")
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		},
+		async run({ data }, { abbreviation, ...refArgs }) {
+			const target = refOf(refArgs);
+			return "error" in target ? error(target.error) : json(await data.setAbbreviation(target.ref, abbreviation));
+		}
+	})
+];
+const writeNotifications = [define({
+	name: "mark_notification_read",
+	scope: "write:notifications",
+	description: "通知を 1 件、既読にして返す",
+	inputSchema: { id: z.number().describe("通知の id") },
+	annotations: {
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	async run({ data }, { id }) {
+		return json(await data.markNotificationRead(id));
+	}
+}), define({
+	name: "mark_all_notifications_read",
+	scope: "write:notifications",
+	description: "未読の通知をすべて既読にし、既読にした件数を返す",
+	inputSchema: {},
+	annotations: {
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: true
+	},
+	async run({ data }) {
+		return json(await data.markAllNotificationsRead());
+	}
+})];
+/** すべての道具。出す順は、読み取り、書き込みの順 */
+const TOOLS = [
+	...readLessons,
+	...readTransit,
+	...writeEvents,
+	...writeCourses,
+	...writeNotifications
+];
+/** 道具の処理で起きた失敗を、利用者に見せる文にする。想定外の例外は、そのまま投げる */
+function failureMessage(caught) {
+	if (caught instanceof FunmaryToolFailure) return caught.message;
+	if (typeof caught === "object" && caught !== null && "name" in caught) {
+		const named = caught;
+		if (named.name === "FunmaryApiError" && typeof named.message === "string") {
+			const body = named.body;
+			if (named.code === "ambiguous" && Array.isArray(body?.candidates)) return ambiguousMessage(named.message, body.candidates);
+			return named.message;
+		}
+	}
+	return null;
+}
+//#endregion
+//#region src/server.ts
+function toResult(output) {
+	if (output.kind === "error") return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: output.message
+		}]
+	};
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(output.value)
+		}],
+		structuredContent: output.value
+	};
+}
+/** 範囲に合う道具を、サーバーに登録する。登録した道具の名前を返す */
+function registerTools(server, options) {
+	const context = {
+		data: options.data,
+		now: options.now ?? (() => /* @__PURE__ */ new Date())
+	};
+	const registered = [];
+	for (const tool of TOOLS) {
+		if (!options.scopes.includes(tool.scope)) continue;
+		if (options.enabled && !options.enabled(tool)) continue;
+		server.registerTool(tool.name, {
+			description: tool.description,
+			...tool.inputSchema ? { inputSchema: tool.inputSchema } : {},
+			annotations: tool.annotations
+		}, async (args) => {
+			try {
+				return toResult(await tool.run(context, args ?? {}));
+			} catch (caught) {
+				const message = failureMessage(caught);
+				if (message === null) throw caught;
+				return toResult({
+					kind: "error",
+					message
+				});
+			}
+		});
+		registered.push(tool.name);
+	}
+	return registered;
+}
+/** 道具を登録した MCP サーバーを作る */
+function createFunmaryMcpServer(options) {
+	const server = new McpServer({
+		name: options.name ?? "funmary",
+		version: options.version ?? "1",
+		...options.icons ? { icons: [...options.icons] } : {}
+	});
+	registerTools(server, options);
+	return server;
+}
+//#endregion
+//#region src/stdio.ts
+/** サーバーを起動して、標準入出力に結ぶ。トークンが使えなければ、理由の分かる文で、例外にする */
+async function runStdioServer(options) {
+	const client = createFunmaryClient({
+		baseURL: options.baseURL,
+		token: options.token
+	});
+	let scopes;
+	try {
+		scopes = (await client.me()).scopes;
+	} catch (error) {
+		if (error instanceof FunmaryApiError && error.status === 401) throw new Error("アクセストークンが使えません。設定画面で発行し直してください", { cause: error });
+		throw error;
+	}
+	await createFunmaryMcpServer({
+		data: createClientData(client),
+		scopes,
+		...options.version ? { version: options.version } : {}
+	}).connect(new StdioServerTransport());
+}
+//#endregion
+export { failureMessage as a, ambiguousMessage as c, TOOLS as i, createFunmaryMcpServer as n, createClientData as o, registerTools as r, FunmaryToolFailure as s, runStdioServer as t };

package/package.json

@@ -1,19 +1,43 @@
 {
   "name": "@funmary/mcp",
-  "version": "0.0.0-reserved",
-  "main": "index.js",
-  "scripts": {
-    "help": "node scripts/main.js --help",
-    "reserve": "node scripts/main.js"
+  "version": "1.0.0",
+  "description": "Funmary の MCP サーバー。手元で動かす (stdio) 入口と、サーバーと共有する道具の定義",
+  "license": "(BSD-3-Clause OR Apache-2.0)",
+  "author": "funmary (https://github.com/funmary-app)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/funmary-app/funmary.git",
+    "directory": "packages/public/mcp"
   },
+  "type": "module",
   "files": [
-    "index.js"
+    "dist"
   ],
-  "keywords": [],
-  "author": "funmary",
-  "description": "[Reserved]",
+  "bin": {
+    "funmary-mcp": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@funmary/client": "1.0.0",
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "zod": "^4.6.5"
+  },
   "devDependencies": {
-    "consola": "^3.4.2",
-    "dotenv": "^17.3.1"
+    "tsdown": "^0.23.0"
+  },
+  "scripts": {
+    "build": "tsdown"
   }
 }

package/index.js

@@ -1 +0,0 @@
-module.exports = console.log("@funmary/mcp is reserved for funmary");